ZetCode

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.

cow_alias.py
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.

cow_view.py
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.

cow_subframe.py
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.

cow_safe.py
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.

cow_copy.py
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

I am Jan Bodnar, a programmer and technical writer. I have been writing programming tutorials at ZetCode since 2007 and have published eight e-books. See about the author.

List all Pandas tutorials.