pandas 3.1 写时复制:五处赋值悄悄失效
升级完依赖,测试照样全绿,日志里没有任何异常,第二天发现报表里的 total 还是旧值。这类问题在 pandas 3.x 上会成批出现,因为写时复制(Copy-on-Write,下称 CoW)已经从「可选的未来行为」变成了唯一行为。
官方迁移指南的原话是 Copy-on-Write is the default and only mode in pandas 3.0.,另一句更直白:Chained assignment will never work。前一句只是宣布规则,后一句才是会让代码出事的部分——它不是说「不推荐」,而是说「永远不会生效」。
我实际测试的方式很简单:同一台 Windows 11 机器、同一个 CPython 3.13.14,把 pandas 2.3.1 和 3.1.0 分别装在两个路径下,跑同一份 20 个用例的脚本,逐行比对输出。下面所有数字都是这样得来的,不是抄来的。
先把结论摆出来
如果只记五条:
1. df["col"][mask] = x 这类链式赋值,在 3.x 上永远不改数据,只发一个 ChainedAssignmentError 警告,不是异常,不会中断脚本。
2. 作用在「选出来的列」上的 inplace=True(如 df["col"].replace(1, 5, inplace=True))同样永远不改数据,而且它连返回值都变了:2.x 返回 None,3.x 返回一个新的 Series。
3. Series.to_numpy()、.values、np.asarray(series) 现在都返回只读数组,写一下就是 ValueError: assignment destination is read-only。
4. pd.Series(numpy_array) 默认复制数组,之后改 numpy 数组不再影响 Series;想保留共享必须显式写 copy=False。
5. SettingWithCopyWarning 这个类已经被删掉了,任何 except pd.errors.SettingWithCopyWarning 或 hasattr 判断都会走到另一条分支。
还有三处不在 CoW 范围内、但同样会静默改变结果的默认值变化:字符串列默认 dtype 从 object 变成 str、日期时间默认分辨率从纳秒变成微秒、以及由此带来的「转成整数后小 1000 倍」。这三条我放在第三节单独说,因为它们比 CoW 更难排查。
这次对拍的环境与口径
- 版本:pandas
3.1.0(2026-10-22 发布)、对照2.3.1;numpy2.5.4与2.3.1;CPython3.13.14;Windows 11。 - 版本来源:GitHub Releases 与 PyPI 两处都取过,3.1.0 是当前最新稳定版,3.0.0 发布于 2026-01-21,中间还有 3.0.1 至 3.0.6 六个补丁版。
- 安装方式:
pip install --target tmp/pd31 pandas==3.1.0装到隔离目录,靠PYTHONPATH切换,不动主环境。 - 判定口径:每个用例同时打印「数据变成什么」和「抛出/发出了什么」,只比对这两项。凡是我没亲手跑过的,下面都会写明「官方标称」,不会写成实测。
官方给的最低要求也顺便记一下:pandas 3.0 起要求 Python ≥ 3.11、numpy ≥ 1.26,pytz 不再是必需依赖。
一、不再改数据的五处写法
1. 链式赋值:从「有时管用」变成「永远不管用」
这是最容易炸的一类。2.x 里 df["foo"][df["bar"] > 5] = 100 在多数情况下是真的生效的,只是会发一条 FutureWarning 提醒你将来会变。
我在 2.3.1 上跑这句,foo 变成 [1, 2, 100],符合预期;换到 3.1.0,同一句跑完 foo 仍是 [1, 2, 3],只有一个 ChainedAssignmentError 警告:
ChainedAssignmentError: A value is being set on a copy of a DataFrame or Series
through chained assignment. Such chained assignment never works to update the
original DataFrame or Series, because the intermediate object on which we are
setting values always behaves as a copy.
注意这是一个 warning,不是 exception。默认的警告过滤器下它只打印一次,try/except 抓不到,脚本 exit code 仍是 0。跑批作业最容易在这里静默出错。
顺带一个容易误判的点:df.loc[mask]["foo"] = 100 和 df[mask]["foo"] = 100 这两种写法在 2.3.1 上就已经不生效了,当时发的是 SettingWithCopyWarning。所以它们在 3.x 上「失效」并不算新问题,只是警告类型换了。真正从「生效」变「不生效」的是 df["col"][mask] = x 这一种。
正确写法只有一种,就是一次索引到底:
df.loc[df["bar"] > 5, "foo"] = 100
这句在 3.1.0 上跑出 [1, 2, 100],没有警告。
2. 列上的 inplace:不生效,返回值还变了
df["foo"].replace(1, 5, inplace=True) 在 2.3.1 上把 df 改成了 [5, 2, 3],并返回 None;3.1.0 上 df 仍是 [1, 2, 3],而返回值变成了一个 Series。官方原文对此的表述是 Updating a column selected from a DataFrame with an inplace method will also not work anymore.,归类同样是「另一种形式的链式赋值」。
同一类还有 df["a"].fillna(0, inplace=True):2.3.1 返回 None,3.1.0 返回 Series,并且发一条同类警告。
这里藏着一个比「没改数据」更阴的坑:inplace=True 的返回值语义整体变了。3.0 的 whatsnew 里有一条明确写着,replace / fillna / ffill / bfill / interpolate / where / mask / clip 在 inplace=True 时现在返回 self(原对象)而不是 None。我实测 df.replace({"foo": {1: 5}}, inplace=True),2.3.1 返回 None,3.1.0 返回的对象 is df 为 True。
于是下面这种老代码会静默改变行为:
if df.fillna(0, inplace=True) is None:
... # 3.x 上永远不成立
改成什么都不会报错,只是分支永远不进去。
3. 选中列上的 attrs 不再保留
attrs 是 pandas 给对象附加元数据的口子,很多团队拿它存单位、数据源、上游表名。官方迁移指南里有一句很短的话:Attributes set on a selected column do not persist——原因是选列现在每次都返回一个新的 Series 对象,不再有缓存。
实测:给 df["foo"].attrs["unit"] = "kg" 赋值后,2.3.1 上再次访问 df["foo"].attrs 能看到 {'unit': 'kg'};3.1.0 上是空字典 {}。没有任何警告,因为从语法上看你确实改了一个对象,只是那个对象下一秒就没了。
正确做法是把元数据挂在父 DataFrame 的 attrs 上,或者干脆另开一列存。
4. `to_numpy()` 返回只读数组
这条至少有明确报错,算是五条里最友善的。
pd.Series([1, 2, 3]).to_numpy() 在 2.3.1 上 writeable 为 True,写进去 Series 会跟着变成 [99, 2, 3]——这是老 bug 的典型形态。3.1.0 上 writeable 为 False,写入直接抛:
ValueError: assignment destination is read-only
.values 与 np.asarray(series) 三条路径在 3.1.0 上全部只读,行为一致。
但官方给了一个「逃生门」:You can also make the array writeable again if you don't care about the pandas object anymore. 我照着试了——arr.flags.writeable = True 再写,Series 真的跟着改了,np.shares_memory 仍是 True。也就是说这道门一开,CoW 刚刚替你挡掉的那个 bug 会原样回来。需要改数组就老老实实 arr.copy()。
5. 构造函数默认复制 numpy 数组
官方原文:The Series and DataFrame constructors now copies a NumPy array by default when not otherwise specified.
实测:a = np.array([1, 2, 3])、s = pd.Series(a)、再执行 a[0] = 99——2.3.1 上 s 变成 [99, 2, 3](共享内存),3.1.0 上 s 仍是 [1, 2, 3]。
想保留共享必须写 pd.Series(a, copy=False),这一条在 3.1.0 上我实测仍然共享(改数组后 Series 变成 [99, 77, 3])。反过来说,如果你之前依赖共享来省内存,升级后会多一份拷贝,大数组场景要留意内存峰值。
二、写时才复制到底省了什么
CoW 的实现是「尽量共享、写的时候再复制」,所以它既不是「全都复制」也不是「全都不复制」。用 np.shares_memory 能直接把这件事量出来。
1,000 行 4 列的 frame,取一个切片 v = df[:]:
| 动作 | pandas 2.3.1 | pandas 3.1.0 |
|---|---|---|
| 切片后是否共享内存 | True | True |
写 v.iloc[0, 0] 后是否共享 | True | False |
| 父对象是否被改 | True | False |
三个格子把 CoW 说清楚了:切片是惰性的(仍然共享),写入那一刻才复制,父对象因此安全。2.3.1 那一列第二、三行是 True/True,就是老行为——改切片会改到父对象。
复制是有成本的,成本可以量。1,000,000 行 × 4 列 float64(约 32 MB):
- 对象独占、直接写:
0.000249 s - 存在活着的父引用、写入触发复制:
0.004095 s,慢 16.4 倍
同一个 frame 上,df.copy() 要 0.007724 s,而 df[:] 只要 0.000081 s,省下 98.9% 的耗时。这就是官方说「SettingWithCopyWarning 被删掉、为消警告加的防御性 .copy() 不再需要」的实际价值:那一行 .copy() 现在纯粹是白花的钱。官方原话是 the SettingWithCopyWarning is removed, and defensive .copy() calls to silence the warning are no longer needed.
反过来的代价也在这里:如果你为了「性能」故意留一堆对同一份数据的引用,CoW 会在第一次写时让你付一次完整拷贝,而且这次拷贝是隐式的、不出现在性能分析的显式调用里。
三、换了错法的三处:不是 CoW,但更疼
这三条严格说不属于 CoW,但都随 3.0 一起来,且都不会抛异常。
1. 字符串列默认 dtype 从 object 变成 str
官方原文:Starting with pandas 3.0, a dedicated string data type is enabled by default (backed by PyArrow under the hood, if installed, otherwise falling back to being backed by NumPy object-dtype).
实测 pd.Series(["a", "b"]).dtype:2.3.1 是 object,3.1.0 是 str。于是任何 if df["col"].dtype == object: 的判断在 3.x 上全部走 else 分支,我实测该比较返回 False。
新 dtype 只装字符串和缺失值,所以混类型写入会直接报错:
TypeError: Invalid value '1' for dtype 'str'. Value should be a string or
missing value, got 'int' instead.
2.3.1 上同样的操作会静默得到 [1, 'b']——一列里混了两种类型,后面 sum() 或排序才发现不对。这条算是「用报错代替静默」,方向是好的,但前提是你的清洗脚本别指望它能塞进去整数。
2. 日期时间默认分辨率从 ns 变成 us
官方原文:The new default resolution when parsing strings is microseconds, falling back to nanoseconds when the precision of the string requires it.
实测 pd.to_datetime(["2026-01-01 00:00:00.123456"]).dtype:2.3.1 是 datetime64[ns],3.1.0 是 datetime64[us]。
3. 转整数后小 1000 倍
这是全套变更里唯一会造成「数值错但不报错」的一条,官方 whatsnew 专门加了一句警告:One big exception is converting to integers, which will give integers 1000x smaller.
同一个时间戳 2026-01-01 00:00:00.123456:
- 2.3.1:
astype("int64")→1767225600123456000 - 3.1.0:
astype("int64")→1767225600123456
差了整整 1000 倍。如果你的代码把时间戳转成整数存进数据库、或者当缓存 key、或者跟外部系统对时间,这一条会静默产生错位数据,而且两边都能跑通。官方建议是别用 astype("int64"),或者先用 as_unit() 把单位钉死再转。
四、升级之前怎么把这类写法找出来
官方给的路径是「先升到 2.3,把警告跑干净,再升 3.0」。这条建议我验证了一半:2.3.1 上跑链式赋值确实会发 FutureWarning,内容里直接写着 ChainedAssignmentError: behaviour will change in pandas 3.0!。所以升级前用 2.3 跑一遍带警告即错误的测试是有用的:
python -W error::FutureWarning -m pytest
需要说清楚边界:我只验证了「2.3.1 会对链式赋值发 FutureWarning」这一个点,没有验证它能覆盖全部 11 组差异。像 attrs、构造函数复制、inplace 返回值这三条,2.3.1 上完全不发警告——它们是升级那一刻才改变的,任何前置检查都抓不到。这三条只能靠读迁移指南加人工核对。
pd.options.mode.copy_on_write 这个开关也别指望了。3.1.0 上把它设成 True 或 "warn" 都能设置成功,但同时会抛 Pandas4Warning:
The 'mode.copy_on_write' option is deprecated. Copy-on-Write can no longer be
disabled (it is always enabled with pandas >= 3.0), and setting the option ...
也就是说开关「接受」了你的值,但什么也不做。这类「接受但无效」的配置最坑,因为它会让排查方向跑偏——你以为自己关掉了 CoW。
五、踩坑录:四个真实报错与改法
下面四条都在本机 3.1.0 上原样跑出来过,报错文字是原文。
报错一:assignment destination is read-only
现象:把 to_numpy() 的结果当缓冲区写。
ValueError: assignment destination is read-only
原因:CoW 下 pandas 对象的底层数组对外只读,防止绕过 CoW 改到别的对象。
解决:要改就 arr = s.to_numpy().copy();如果只是想拿一份可写数组喂给别的库,.copy() 是唯一正确姿势。不要用 arr.flags.writeable = True,我实测它会连带改掉原 Series。
报错二:Invalid value '1' for dtype 'str'
现象:往字符串列里塞数字,或者用 NaN 以外的哨兵填缺失。
TypeError: Invalid value '1' for dtype 'str'. Value should be a string or
missing value, got 'int' instead.
原因:3.0 起字符串列是专用 str dtype,只收字符串与缺失值。
解决:写入前显式转换(str(x)),或者在建表时指定 dtype=object 保留旧行为——但要清楚这等于放弃新 dtype 的内存与速度收益。
报错三:module 'pandas.errors' has no attribute 'SettingWithCopyWarning'
现象:老代码里有 except pd.errors.SettingWithCopyWarning: 或 hasattr 探测。
AttributeError: module 'pandas.errors' has no attribute 'SettingWithCopyWarning'
原因:该警告类随 CoW 一起被删除,官方原话是「因为现在一致地永不生效,所以删除」。
解决:删掉这段兼容代码;如果确实要兼容 2.x 与 3.x,用版本判断而不是 hasattr(hasattr 在 2.3.1 上返回 True,同一份代码两条路径都能跑,但语义完全不同)。
报错四:链式赋值只发警告不报错
现象:跑批任务 exit code 为 0,数据没改。
ChainedAssignmentError: A value is being set on a copy of a DataFrame or Series
through chained assignment. Such chained assignment never works to update ...
原因:两步索引,第一步返回的是副本。
解决:合并成一次 loc。另外建议在 CI 里加一条 python -W error::pandas.errors.ChainedAssignmentError,把它变成硬失败——反正它现在永远不生效,早失败比晚失败好。
六、这篇没覆盖到的部分
按老规矩把边界写清楚,避免把「我没测」读成「不存在」:
- 没测 PyArrow 后端的字符串 dtype。本机没有 pyarrow,3.1.0 落到了 NumPy object 后端;装了 pyarrow 之后内存占用与
.str访问速度都会不同,这部分我没数据。 - 没测 IO 层。
read_csv/read_excel在 3.x 里的 dtype 推断与列类型变化,我一行都没跑。 - 没测多进程与多线程场景。CoW 的引用计数在并发下是否有额外开销,需要单独设计实验。
- 没测 pandas 1.x 直升 3.x 的路径。官方建议先到 2.3,我只验证了 2.3.1 到 3.1.0 这一段。
- 没测
offsets.Day的语义变化(从固定 24 小时改成日历日)。这条我只读了 whatsnew,没有实测。
如果你的项目里有一堆 .copy(),或者有一批「先选列再赋值」的老代码,那升级到 3.x 之前值得先跑一遍第四节那条命令,再人工过一遍 attrs、构造函数、inplace 返回值这三处不报警的地方。
顺带说一句,这类「默认值悄悄换了」的坑不只 pandas 有。之前写 DuckDB 1.5 的 CSV 嗅探 和 Parquet 默认字典编码 时,踩的都是同一个套路:工具给了你一个默认值,文档写了,但没人告诉你它会改变结果。同一条线上的 json 与 orjson、msgspec 的九处默认值 也是这么写的,可以对着看。
本文不含任何联盟推广链接,也没有佣金关系;文中所有数字来自本机实测或官方文档,官方原文均已标注出处。
👉 立即参与小米 MiMo 开放平台:国内领先的 AI 大模型开放平台,高性价比推理服务
👉 立即参与阿里云 AI:汇集爆款 AI 产品,热门模型专属权益优惠券助力企业创新加速
📌 本文由 AI 辅助生成并经人工审核发布 | TechPassive — AI 驱动的内容测试站点,专注于效率工具与 SaaS 真实评测
🔗 精选推荐工具
使用以下链接支持我们持续产出高质量内容(点击可直接前往购买):
作为亚马逊联盟会员,符合条件的购买会为我们带来佣金,不会增加你的购买成本。