In-place patching
Apply corrections or refreshed values to existing rows and columns without changing the target schema.
Pandas · Module
df.update
DataFrame.update mutates a DataFrame with aligned, non-missing values from another object. It preserves the target’s shape and can either overwrite populated cells or fill only missing ones.
How it works
DataFrame.update aligns another DataFrame by index and column labels, then mutates the original object with eligible non-missing values. By default, incoming values replace existing ones; options can restrict updates to missing cells, filter candidates, or raise on overlapping non-missing data.
Syntax
DataFrame.update(other, join='left', overwrite=True, filter_func=None, errors='ignore')Parameters
| Name | Type | Description |
|---|---|---|
other | DataFrame or object coercible into a DataFrame | DataFrame or object coercible into a DataFrame; a Series must have a name used as its column label for alignment. |
join | 'left', default 'left' | Only 'left' is implemented; preserves the target's index and columns. |
overwrite | bool, default True | Controls whether aligned non-NA incoming values replace existing target values; false updates only target NA values. |
filter_func | callable(1d-array) -> bool 1d-array, optional | Callable receiving a one-dimensional array and returning a boolean one-dimensional array; True marks values to update. |
errors | 'raise' or 'ignore', default 'ignore' | Controls conflicts where both objects have non-NA overlapping data; 'raise' raises ValueError. |
Returns
None; the DataFrame is modified in place.
Key points
- The target DataFrame is mutated directly, using non-missing values from the supplied object.
- The source should share at least one row or column label with the target so alignment can locate update positions.
- The default overwrite=True replaces existing target values where aligned incoming values are non-missing.
- Setting overwrite=False makes updates fill missing target cells rather than replace populated ones.
- filter_func allows a callable to select update positions beyond the usual missing-value cases.
- Updating preserves the target's row count; incoming rows outside the target's labels are not appended.
Common mistakes
- The operation cannot expand the target's index or columns: join only accepts the left-join behavior, so unmatched labels from the other object are ignored.
- A Series input needs a name because that name supplies the column label used for alignment.
- The method mutates the target and returns None; do not assign its result as the updated DataFrame.
Example: Update matching values in place
import pandas as pd
df = pd.DataFrame({"A": [1, 2, 3], "B": [400, 500, 600]})
updates = pd.DataFrame({"B": [4, 5, 6], "C": [7, 8, 9]})
df.update(updates)
print(df)The matching B values are changed in place; the unmatched C column is not added.
When to use it
Missing-value filling
Populate gaps from a second aligned DataFrame while preserving values already present.
Validation before replacement
Enforce conflict detection when incoming and existing datasets both contain values for the same aligned cells.
Interview questions
QWhat does DataFrame.update do?
It aligns the other object on row and column labels and updates the target in place with non-missing incoming values. The target keeps its original shape, so unmatched labels do not add rows or columns.
Follow-up: How would you update only missing target cells? Use overwrite=False, which limits changes to positions where the original DataFrame is NA.
QHow do overwrite and filter_func affect updates?
With overwrite=True, overlapping non-missing values from other replace target values. With overwrite=False, only target cells that are missing are eligible for replacement.
Follow-up: Can non-missing target values still be changed when overwrite=False? Yes, a filter_func can select values to update, including values other than NA.
QWhen should errors='raise' be used?
errors='ignore' is the default and permits overlapping non-NA values to be replaced according to the update rules. errors='raise' instead raises ValueError when both objects contain non-missing data at an overlapping position.
Follow-up: What shape-changing join can update perform? None: only a left join is implemented, preserving the original index and columns.
Related
DataFrame.combine_firstDataFrame.mergeDataFrame.joinDataFrame.align