Pandas Copy-on-Write
last modified November 17, 2026 Python 3.15
Copy-on-write is a rule for objects that share data: a shallow copy shares the underlying data until one of the objects is modified, and at that moment the data is copied so that the other object is left untouched. In Pandas this means that deriving a Series or a filtered frame from a DataFrame gives you a safe object to work with: changes to it cannot silently alter the original.
The behaviour was opt-in through an option in pandas 2.x. Since pandas 3.0 it
is always enabled and can no longer be switched off. In pandas 3.1.1, the
version used for these examples, merely reading that option emits a
Pandas4Warning announcing the option's removal; that is why we do
not read or set it here and demonstrate the behaviour directly instead.
An alias is not a copy
Writing df2 = df only binds a second name to the very same
Python object; no new DataFrame and no shared data are created. Changing
through that name therefore changes the object that both names refer to.
This is ordinary Python assignment, and copy-on-write is not involved.
import pandas as pd
df = pd.DataFrame({'a': [1, 2], 'b': [3, 4]})
df2 = df
df2.loc[0, 'a'] = 99
print('df:')
print(df)
print()
print('df2:')
print(df2)
Both printed frames show 99 in the first row because they are one object. If
you want an independent frame, call copy() as shown near the end
of this article; a bare assignment never isolates data.
$ python cow_alias.py
df:
a b
0 99 3
1 2 4
df2:
a b
0 99 3
1 2 4
Modifying a derived Series
Selecting a single column, as in s = df['a'], really does create
a new object that shares data with the frame. Under copy-on-write, assigning
into s copies the data first, so the original frame stays as it
was. The iloc indexer used below addresses rows and columns by
integer position.
import pandas as pd
df = pd.DataFrame({'a': [1, 2], 'b': [3, 4]})
s = df['a']
s.iloc[0] = 99
print('after changing the Series:')
print(df)
print()
print('the Series itself:')
print(s)
The Series now starts with 99, but df still holds 1 in that cell.
The write triggered a copy, which is exactly the guarantee copy-on-write
provides. Older Pandas versions could not promise this and often warned
instead.
$ python cow_view.py after changing the Series: a b 0 1 3 1 2 4 the Series itself: 0 99 1 2 Name: a, dtype: int64
Chained assignment no longer writes through
Chained assignment means indexing more than once in a single
statement, for example filtering a frame and then assigning into the result.
In older versions this sometimes modified the original and sometimes did not,
so Pandas issued a SettingWithCopyWarning to flag the uncertainty.
With copy-on-write the intermediate result is a separate object that behaves
like a copy, so the update never reaches the original. Here the two steps are
written separately to make that explicit.
import pandas as pd
df = pd.DataFrame({'a': [1, 2, 3]})
sub = df[df['a'] > 1]
sub['a'] = 0
print('original DataFrame:')
print(df)
print()
print('filtered sub-frame:')
print(sub)
The filtered frame contains the values that passed the condition and they are
changed to 0, while df keeps 1, 2 and 3. Written as the single
expression df[df['a'] > 1]['a'] = 0, pandas 3 raises a
ChainedAssignmentError to tell you the statement can never update
the original; the two-step form above shows the same effect without that
warning.
$ python cow_subframe.py original DataFrame: a 0 1 1 2 2 3 filtered sub-frame: a 1 0 2 0
Safe explicit assignment with loc
When you do want to change the original frame, use one indexed assignment:
loc takes a row selector and a column name and writes directly to
the object you called it on. This is the recommended replacement for chained
assignment and works identically with copy-on-write enabled.
import pandas as pd
df = pd.DataFrame({'a': [1, 2, 3]})
df.loc[df['a'] > 1, 'a'] = 0
print(df)
The rows that satisfied the condition now hold 0. Because the assignment is
performed on df itself in a single step, there is no ambiguity
about which object is changed and no warning is produced.
$ python cow_safe.py a 0 1 1 0 2 0
Making an explicit copy
For a frame that you intend to edit freely, ask for a copy with
copy(). By default this is a deep copy: the new frame owns its
data from the start, so later edits are independent regardless of the
copy-on-write rules.
import pandas as pd
df = pd.DataFrame({'a': [1, 2], 'b': [3, 4]})
df2 = df.copy()
df2.loc[0, 'a'] = 99
print('original a:', df['a'].tolist())
print('copy a: ', df2['a'].tolist())
Only the copy's first value changes. Contrast this with the alias example at
the top: assignment binds a name, while copy() creates a distinct
object. Explicit copying is the clearest way to signal intent in code.
$ python cow_copy.py original a: [1, 2] copy a: [99, 2]
Source
Pandas Copy-on-Write Documentation, Pandas Copy-on-Write Migration Guide, Pandas 3.0 Release Notes, and Pandas DataFrame.copy Documentation
In this article we have seen how shared data behaves under copy-on-write, why
an alias differs from a derived object, why chained assignment no longer
writes through, how loc performs a safe update, and how
copy() creates an independent frame. For grouping operations
that return new objects see the
grouping data tutorial, and for the
memory consequences see Pandas memory usage.
Author
List all Pandas tutorials.