Advanced2026-11-097 min read

How to Rename Columns in R (dplyr, Base R and data.table)

To rename a column in R with dplyr, use rename(df, new_name = old_name), for example df <- rename(df, birth_year = DOB). Note the order: the new name goes on the left of the =. Without packages, base R does the same with names(df)[names(df) == "DOB"] <- "birth_year".

Which one to use depends on what else you are doing. dplyr reads cleanly inside a pipeline, base R needs no dependencies, and data.table's setnames() renames in place without copying, which matters for very large tables. This guide covers all three, plus pattern-based renaming with rename_with() and the errors people hit most often. The syntax follows the current documentation for dplyr 1.2 and data.table.

The examples use this data frame:

df <- data.frame(
  `First Name` = c("Ada", "Alan"),
  DOB = c(1815, 1912),
  score = c(90, 85),
  check.names = FALSE
)

check.names = FALSE keeps the space in "First Name"; by default data.frame() would turn it into First.Name.

Rename columns with dplyr::rename()

library(dplyr)

df <- rename(df, birth_year = DOB)

Or in a pipeline, with either pipe:

df <- df |>
  rename(
    first_name = `First Name`,
    birth_year = DOB
  )

Things to know about rename():

  • It is always new = old. Swapping them is the most common mistake, and dplyr will complain that the column you wrote on the right doesn't exist.
  • Names with spaces or other special characters need backticks around them, as in the pipeline example above. A quoted string also works on the right-hand side: first_name = "First Name".
  • Every other column is kept, in its original position. If you want to rename and keep only some columns, select() renames too: select(df, first = "First Name", score).
  • You can refer to a column by position: rename(df, birth_year = 2) renames the second column.
  • rename() returns a new data frame. Assign it back, or nothing changes.

Rename from a lookup vector

When the mapping lives in a variable (say, you read it from a config file), put it in a named character vector, again with new names as the names and old names as the values, and pass it through all_of() or any_of():

lookup <- c(first_name = "First Name", birth_year = "DOB", region = "Region")

df <- rename(df, any_of(lookup))

all_of() throws an error if any old name is missing from the data. any_of() quietly skips the missing ones, which is handy when the same lookup is used for files that don't all have the same columns. In the example above, "Region" doesn't exist, so any_of() just ignores it.

Rename many columns with rename_with()

rename_with() applies a function to column names. By default it touches every column; the third argument narrows it down with the same helpers you use in select():

# Uppercase every name
rename_with(df, toupper)

# Lowercase and replace spaces with underscores
rename_with(df, ~ tolower(gsub(" ", "_", .x)))

# Only the numeric columns get a prefix
rename_with(df, ~ paste0("x_", .x), where(is.numeric))

# Only columns that start with "Q"
rename_with(df, ~ sub("^Q", "quarter_", .x), starts_with("Q"))

In the formula, .x is the vector of current names. You can also use R's own anonymous function syntax, \(x) tolower(x), or a named function. The function must return the same number of names it received.

If you just want tidy snake_case names for everything, the janitor package does it in one call: janitor::clean_names(df) turns "First Name" into first_name and also handles punctuation and duplicate names.

Rename columns in base R

One column by name

names(df)[names(df) == "DOB"] <- "birth_year"

This reads as "of the names, the one equal to DOB, replace with birth_year". If no name matches, nothing happens and no error is raised, so a typo goes unnoticed. Check the result with names(df).

One column by position

names(df)[2] <- "birth_year"

Short, but brittle: if the column order changes, you rename the wrong column.

All columns at once

names(df) <- c("first_name", "birth_year", "score")
# or
colnames(df) <- c("first_name", "birth_year", "score")

For a data frame, names() and colnames() are equivalent. colnames() also works on matrices, which have no names() for columns. The vector must have one name per column. There is also setNames(df, c(...)), which returns a renamed copy, useful inside a pipe.

Transform all names

names(df) <- tolower(names(df))
names(df) <- gsub(" ", "_", names(df))
names(df) <- make.names(names(df))   # make them syntactically valid

Rename columns with data.table::setnames()

library(data.table)
DT <- as.data.table(df)

setnames(DT, "DOB", "birth_year")
setnames(DT, c("First Name", "score"), c("first_name", "points"))

setnames() changes the names by reference: there is no <-, and no copy of the data is made, which is why it is preferred for large tables. It also works on plain data frames.

More forms from the documentation:

setnames(DT, 2, "birth_year")        # by position
setnames(DT, tolower)                # apply a function to all names
setnames(DT, 2:3, toupper)           # apply a function to some names
setnames(DT, c("a", "b", "c"))       # replace all names

setnames(DT, old, new, skip_absent = TRUE)

By default setnames() stops with an error if an old name isn't found; skip_absent = TRUE skips missing ones instead, the data.table equivalent of any_of().

On a data.table, prefer setnames() over names(DT) <- ...: the assignment form can copy the table, which defeats the point of using data.table.

Which method to choose

SituationUse
Inside a dplyr pipelinerename(new = old)
Mapping stored in a variablerename(any_of(lookup))
Same transformation for many namesrename_with() or janitor::clean_names()
No packages, one columnnames(df)[names(df) == "old"] <- "new"
Replace every namenames(df) <- c(...)
Large data.tablesetnames(DT, old, new)

Common errors

Column doesn't exist: you probably wrote rename(df, DOB = birth_year) with the names reversed, or the name has a hidden space or different case. Run names(df) and copy the name exactly.

Unexpected = or symbol: the column name contains a space or starts with a number and isn't wrapped in backticks.

Changes don't stick: rename() and setNames() return a new object. Write df <- rename(df, ...). Only data.table's setnames() modifies the original.

Names got dots instead of spaces: read.csv() and data.frame() apply make.names() by default. Pass check.names = FALSE to keep the original headers, or use readr::read_csv(), which keeps them as they are.

Good column names follow the same logic as good file names: lowercase, no spaces, a single separator. Our naming conventions guide covers the trade-offs. For the same task in other tools, see rename columns in pandas and rename a column in SQL.

Frequently Asked Questions

How do I rename a column in R?

With dplyr, use df <- rename(df, new_name = old_name). In base R, use names(df)[names(df) == "old_name"] <- "new_name". With data.table, use setnames(DT, "old_name", "new_name"), which renames in place.

How do I rename multiple columns in R at once?

List several pairs in one rename() call, for example rename(df, first_name = fname, last_name = lname). For a rule that applies to many names, use rename_with(), such as rename_with(df, tolower). In data.table, pass vectors: setnames(DT, c("a", "b"), c("x", "y")).

Why does dplyr rename say the column doesn't exist?

Usually the arguments are reversed. rename() takes new_name = old_name, so the existing column must be on the right. Otherwise check for typos, case differences or hidden spaces with names(df), and wrap names containing spaces in backticks.

What is the difference between names() and colnames() in R?

For a data frame they return and set the same thing, the column names. colnames() also works on matrices and other two-dimensional objects, while names() on a matrix refers to element names rather than column names.

How do I rename a column by its position in R?

In base R, names(df)[3] <- "new_name" renames the third column. In dplyr, rename(df, new_name = 3) does the same. In data.table, setnames(DT, 3, "new_name"). Renaming by name is safer when the column order might change.

How do I make all column names lowercase in R?

Use names(df) <- tolower(names(df)) in base R, rename_with(df, tolower) in dplyr, or setnames(DT, tolower) in data.table. janitor::clean_names(df) goes further and converts everything to snake_case.

Ready to organize your files?

Try AI renaming right away. No sign-up needed until you download.

Try It Free