Skip to main content

__ Back to top

__ ` Ctrl ` \+ ` K `

[ ![pandas 2.2.1 documentation - Home](../_static/pandas.svg) ](../index.html)

Site Navigation

  * [ Getting started ](../getting_started/index.html)
  * [ User Guide ](index.html)
  * [ API reference ](../reference/index.html)
  * [ Development ](../development/index.html)
  * [ Release notes ](../whatsnew/index.html)

  * [ __ GitHub  ](https://github.com/pandas-dev/pandas "GitHub")
  * [ __ Twitter  ](https://twitter.com/pandas_dev "Twitter")
  * [ __ Mastodon  ](https://fosstodon.org/@pandas_dev "Mastodon")

Site Navigation

  * [ Getting started ](../getting_started/index.html)
  * [ User Guide ](index.html)
  * [ API reference ](../reference/index.html)
  * [ Development ](../development/index.html)
  * [ Release notes ](../whatsnew/index.html)

  * [ __ GitHub  ](https://github.com/pandas-dev/pandas "GitHub")
  * [ __ Twitter  ](https://twitter.com/pandas_dev "Twitter")
  * [ __ Mastodon  ](https://fosstodon.org/@pandas_dev "Mastodon")

  * [ 10 minutes to pandas ](10min.html)
  * [ Intro to data structures ](dsintro.html)
  * [ Essential basic functionality ](basics.html)
  * [ IO tools (text, CSV, HDF5, â¦) ](io.html)
  * [ PyArrow Functionality ](pyarrow.html)
  * [ Indexing and selecting data ](indexing.html)
  * [ MultiIndex / advanced indexing ](advanced.html)
  * Copy-on-Write (CoW) 
  * [ Merge, join, concatenate and compare ](merging.html)
  * [ Reshaping and pivot tables ](reshaping.html)
  * [ Working with text data ](text.html)
  * [ Working with missing data ](missing_data.html)
  * [ Duplicate Labels ](duplicates.html)
  * [ Categorical data ](categorical.html)
  * [ Nullable integer data type ](integer_na.html)
  * [ Nullable Boolean data type ](boolean.html)
  * [ Chart visualization ](visualization.html)
  * [ Table Visualization ](style.html)
  * [ Group by: split-apply-combine ](groupby.html)
  * [ Windowing operations ](window.html)
  * [ Time series / date functionality ](timeseries.html)
  * [ Time deltas ](timedeltas.html)
  * [ Options and settings ](options.html)
  * [ Enhancing performance ](enhancingperf.html)
  * [ Scaling to large datasets ](scale.html)
  * [ Sparse data structures ](sparse.html)
  * [ Frequently Asked Questions (FAQ) ](gotchas.html)
  * [ Cookbook ](cookbook.html)

  * [ __ ](../index.html)
  * [ User Guide ](index.html)
  * Copy-on-Write (CoW) 

#  Copy-on-Write (CoW)  #

Note

Copy-on-Write will become the default in pandas 3.0. We recommend  turning it
on now  to benefit from all improvements.

Copy-on-Write was first introduced in version 1.5.0. Starting from version 2.0
most of the optimizations that become possible through CoW are implemented and
supported. All possible optimizations are supported starting from pandas 2.1.

CoW will be enabled by default in version 3.0.

CoW will lead to more predictable behavior since it is not possible to update
more than one object with one statement, e.g. indexing operations or methods
wonât have side-effects. Additionally, through delaying copies as long as
possible, the average performance and memory usage will improve.

##  Previous behavior  #

pandas indexing behavior is tricky to understand. Some operations return views
while other return copies. Depending on the result of the operation, mutating
one object might accidentally mutate another:

    
    
    In [1]: df = pd.DataFrame({"foo": [1, 2, 3], "bar": [4, 5, 6]})
    
    In [2]: subset = df["foo"]
    
    In [3]: subset.iloc[0] = 100
    
    In [4]: df
    Out[4]: 
       foo  bar
    0  100    4
    1    2    5
    2    3    6
    

Mutating ` subset  ` , e.g. updating its values, also updates ` df  ` . The
exact behavior is hard to predict. Copy-on-Write solves accidentally modifying
more than one object, it explicitly disallows this. With CoW enabled, ` df  `
is unchanged:

    
    
    In [5]: pd.options.mode.copy_on_write = True
    
    In [6]: df = pd.DataFrame({"foo": [1, 2, 3], "bar": [4, 5,