Written and maintained by CASRAI Editorial Board
Published · Last updated
On this page
Short answer: mutate() is the dplyr function that adds new columns to a data frame, or changes existing ones, while keeping every row. You write one or more name = expression pairs; the expression is evaluated using the data frame’s own columns. This guide is for researchers and analysts who have a data frame in R and need to derive a variable from existing ones (a unit conversion, a centred score, a per-group value) and check that the result is what they intended.
What mutate() is used for in research
Most analysis datasets need derived variables before any model or table: converting units, computing a change score, centring a measure within a cohort, recoding a category, or flagging records. mutate() does this without reducing the number of rows. The official reference describes the result as having the same type as the input, with the same number of rows, modified existing columns keeping their position, and new columns added on the right by default (dplyr reference, mutate(), read 2026-11-08).
It is different from summarise(), which collapses rows. If you need one row per group, see grouping in R; if you need a conditional recode inside a mutate() call, see case_when in R.
Install or access
mutate() is part of the dplyr package, which is also loaded by the tidyverse meta-package. Install it once from CRAN and load it in each session:
install.packages("dplyr")
library(dplyr)
Your data must already be in R as a data frame or tibble. If it is not, start with how to import data in R.
Step-by-step: add a column with mutate()
The examples below use airquality, a data set that ships with R. They are illustrative; the point is the pattern, not the values.
Signature
For a data frame the documented usage is:
mutate(.data, ..., .by = NULL, .keep = c("all", "used", "unused", "none"), .before = NULL, .after = NULL)
1. Add one column
- Pass the data frame as the first argument (or pipe it in).
- Give the new column a name and an expression:
airquality |> mutate(temp_c = (Temp - 32) * 5 / 9)The pipe
|>is the form used in the current dplyr documentation;%>%also works once dplyr is loaded. - Assign the result to an object if you want to keep it:
aq2 <- airquality |> mutate(...).mutate()returns a new data frame; it does not modifyairqualityin place.
2. Add several columns in one call
Separate the pairs with commas. Later expressions can use columns created earlier in the same call:
airquality |> mutate(temp_c = (Temp - 32) * 5 / 9, temp_c_rounded = round(temp_c, 1))
3. Overwrite or delete a column
Using an existing column name replaces that column in its current position. Setting a column to NULL removes it (the reference states that columns given the value NULL are removed):
airquality |> mutate(Temp = (Temp - 32) * 5 / 9, Wind = NULL)
4. Control where the new column appears
.before and .after take a column name or position; by default new columns go on the right-hand side:
airquality |> mutate(temp_c = (Temp - 32) * 5 / 9, .before = 1)
airquality |> mutate(temp_c = (Temp - 32) * 5 / 9, .after = Temp)
5. Choose which columns to keep with .keep
| .keep value | Columns returned |
|---|---|
"all" (default) |
All columns from the input, plus new ones |
"used" |
Only the input columns used in your expressions, plus new ones |
"unused" |
Only the input columns not used in your expressions, plus new ones |
"none" |
No extra input columns, only the new ones |
Per the reference, grouping columns and columns created in ... are always kept. transmute() does the same job as mutate(.keep = "none"); the dplyr documentation marks transmute() as superseded, so prefer .keep = "none" in new code.
6. Compute per group with .by (or group_by)
Expressions in mutate() are evaluated within each group, so the same expression gives a different answer on grouped and ungrouped data. The reference describes .by as an alternative to group_by() that applies to this one operation only:
airquality |> mutate(ozone_centred = Ozone - mean(Ozone, na.rm = TRUE), .by = Month)
Here the mean is calculated separately for each Month. Without .by, the mean would be over the whole data set. With group_by(Month) before mutate() you get the same grouped calculation, but the grouping stays on the result until you call ungroup(); with .by it does not persist. The reference also lists window functions (ranking, lead(), lag(), cumulative functions) as especially useful in grouped mutates.
7. Apply one expression to many columns
The reference shows across() inside mutate() for this. A sketch:
airquality |> mutate(across(c(Ozone, Solar.R), \(x) x / 1000, .names = "{.col}_k"))
Output and how to read it
- Row count is unchanged. If the number of rows changes, the cause is a different function in your pipeline (for example
filter()orsummarise()), notmutate(). - New columns sit on the right unless you used
.beforeor.after; overwritten columns stay where they were. - Missing values propagate.
OzoneinairqualitycontainsNAvalues, so an expression such asOzone - mean(Ozone)returnsNAunless you setna.rm = TRUEinsidemean(). - Check the grouping. Printing a grouped tibble shows a
Groups:line. If you did not mean to leave the data grouped, callungroup()or use.by. - Spot-check a few rows by hand against the source values, particularly for derived variables that feed a statistical model.
Troubleshooting
Could not find function “mutate”
dplyr is not loaded. Run library(dplyr) (or library(tidyverse)) first; if R reports that the package is missing, run install.packages("dplyr").
The new column length does not match
The documented accepted values are a length-1 value (recycled to every row), a vector the same length as the current group (or the whole data frame if ungrouped), NULL, or a data frame. A vector of any other length is not an accepted input, so make sure it is length 1 or matches the group size.
The result is the same for every group
You computed a summary on ungrouped data. Add .by = your_group_column or a preceding group_by().
Later steps behave oddly after mutate()
The data may still be grouped from an earlier group_by(). Check the printed Groups: line and use ungroup().
You expected the original data to change
Assign the output (df <- df |> mutate(...)); the function returns a modified copy.
Free alternatives
dplyr is free and open source. Within base R, the options below need no extra package. For a worked comparison of transform() and mutate(), see transformation in R.
| Approach | What it does | Source note |
|---|---|---|
transform() (base R) |
Evaluates tag=value expressions inside the data frame; matching columns are replaced, others appended |
R manual, transform; its Warning section says it is intended for interactive use and recommends standard subsetting for programming |
within() (base R) |
Listed in the R manual as a more flexible approach than transform() |
R manual, See Also of transform |
mutate() (dplyr) |
Adds or modifies columns, with .by, .keep, .before, .after |
dplyr reference |
FAQ
What does the mutate function do in R?
It creates new columns or modifies existing ones in a data frame using expressions of the existing columns, and returns a data frame with the same number of rows.
What is the difference between mutate() and transmute()?
mutate() keeps all existing columns by default; transmute() keeps only the columns you compute. The dplyr documentation states that transmute() is superseded because mutate(.keep = "none") does the same thing.
How do I use mutate() by group?
Use .by = column inside mutate() for a one-off grouped calculation, or group_by() before it (followed by ungroup()).
How do I delete a column with mutate()?
Assign NULL to it: mutate(df, col = NULL).
Can mutate() make several columns at once?
Yes: list several name = expression pairs separated by commas, or use across() to apply one function to many columns.
Sources
- dplyr reference: Create, modify, and delete columns (mutate), read 2026-11-08.
- dplyr reference: transmute, read 2026-11-08.
- R manual: transform (base package), read 2026-11-08.







