Targeted schema cleanup
Rename a small, known set of columns after reading data with external or legacy names.
Polars · Module
df.rename
Rename DataFrame columns with an explicit old-to-new mapping or a function that derives new names. By default, Polars validates that mapped source names exist.
How it works
Call rename on a DataFrame with either a mapping of existing column names to replacement names or a function that transforms each column name. The operation returns a DataFrame with the resulting schema; strict validation is enabled by default.
Syntax
DataFrame.rename(mapping: Mapping[str, str] | Callable[[str], str], *, strict: bool = True) → DataFrameParameters
| Name | Type | Description |
|---|---|---|
mapping | Mapping[str, str] | Callable[[str], str] | Mapping from old column names to new names, or a callable that accepts an old name and returns its replacement. |
strict | bool = True | Whether to validate that all referenced column names exist in the current schema. |
Returns
DataFrame
Key points
- DataFrame.rename changes the names in a DataFrame’s schema.
- A mapping explicitly pairs each source column name with its replacement.
- Strict validation is enabled by default.
Common mistakes
- With the default strict setting, every name mentioned in a mapping must exist in the current schema; missing names cause an exception.
Example: Rename one column
import polars as pl
df = pl.DataFrame({"foo": [1, 2], "bar": [3, 4]})
renamed = df.rename({"foo": "apple"})
print(renamed)Creates a new DataFrame with the selected column renamed.
When to use it
Systematic naming convention
Apply a consistent prefix, suffix, or transformation to every column name.
Tolerant schema adaptation
Handle optional input columns without raising when some mapped names are absent.
Interview questions
QWhat forms can the mapping argument take?
It accepts either a mapping from old names to new names or a callable that receives each old column name and returns its replacement. It returns a DataFrame with renamed columns.
Follow-up: How would you rename every column using one rule? Pass a callable, such as lambda name: "c_" + name.
QWhat does strict control?
strict defaults to True and validates that all names referenced by the mapping are present in the DataFrame schema. If a referenced name is absent, the operation raises an exception.
Follow-up: How can a caller avoid failure for a mapping that may contain absent names? Set strict=False.
QWhen would you use a callable instead of a mapping?
A dictionary mapping is useful for selected renames, while a callable applies a naming rule to column names. Both approaches produce a DataFrame with the updated column names.
Follow-up: How can you transform names without specifying them individually? Use a callable that derives each new name from the old one.
Related
DataFrame.selectDataFrame.with_columnsDataFrame.columns