ARTICLE · 1302207
PyXL使用详解:在 Excel和WPS里写Python
上一篇《真正本地运行的 Python for Excel & WPS，快到飞起！》讲的是它为什么快：Python 直接跑在本地，不走云端。这一篇接着往下讲用法——PyXL 到底怎么用。没看过那篇也不影响，这篇从零讲起。
先把对象说清楚。PyXL 是 Excel 和 WPS 的加载项。装好之后功能区多一个按钮，点开是侧边栏：左边表格照常用，右边写 Python。
它有个反直觉的地方——你的代码会变成单元格里的一条公式：=PYXL("import polars as pl ...")。代码在公式里，公式在单元格里，源数据一变，结果跟着重算。它不是“导出 CSV 再去脚本里跑”那种外挂，它是一条活的公式。
下面按你实际会碰到的顺序走一遍：界面怎么认、五个设置各管什么、四个按钮区别在哪、xl.read 和 xl.write 的参数、补全怎么用、草稿怎么不丢。参数、快捷键，以及那几个一定会踩到的坑，都讲清楚。
图 1 工作台全貌：环境条、当前单元格、编辑区、三个标签。
先熟悉插件运行界面
别急着写代码。运行界面上有三处信息，后文九成的困惑都跟它们有关。
① 顶部那行字。图里是“Python 3.15.0 已连接 + Polars 2.1.0 + pandas 3.1.0”。这三个数字是当前实际检测到的版本，不是硬性要求。前面的绿点表示解释器已连接；某个库不可用时，这里会直接写“未安装”或“不可用”，不会假装正常。
点这一行文字，打开运行环境；鼠标停上去，能看到解释器路径。这两个操作入口都藏得比较深，值得先记住。
② 右上角那串地址。图里是“示例.xlsx '汇总'!$A$1”。它是工作簿名加当前编辑、也是默认写入的单元格。结果会落在哪，答案就在这一小行字里。选错单元格，结果就返回错地方。
③ 底部三个标签。“结果”“输出”“问题”，加上最底一行状态栏。这三个标签经常被当成一回事，其实分别管预览、运行时信息、静态诊断，后面单独讲。
顺便说主题。PyXL 会跟着宿主走：Excel 的白色、彩色主题显示浅色，深灰、黑色主题则呈深色；WPS 的经典浅色和深色皮肤也会跟着换。宿主设成“跟随系统”时，它跟 Windows 的应用外观；识别不出来的 WPS 皮肤时，默认用浅色。
换主题通常 1.5 秒内更新，代码高亮、设置面板、结果面板一起变，而当前代码、草稿、结果和撤销记录都保留。这点做得挺细——它不是整块刷新，是只换皮。
运行环境：五项设置，一个都不能糊
点顶部环境文字进来，面板长这样：
图 2 运行环境：执行模式、解释器、超时、补全设置。
从上往下一共五项，逐个说。
一、执行模式。外部兼容 / 内嵌高性能 / 自动选择。选了内嵌，下面会自动补一句“同一 Excel 共享 Python 模块。停止会立即取消交付，本机调用结束后才释放运行资源。”
二、高性能入口。在最右边那个勾选框。它跟执行模式不是一回事，下一节专门拆。
三、Python 解释器。下拉框里是扫描结果，图里指向 C:\Python315\python.exe。下面一行小字很关键——“找到 3 个可用解释器”，扫描到几个就写几个。
四、执行超时（秒）。图里是 60，也就是默认值。
五、代码补全设置。折叠着，点开才看到 Node.js 路径，图里是 C:\Program Files\nodejs\node.exe，旁边一个“浏览选择…”。
底部还有一行灰字，别忽略：“环境中需已安装 Polars。更换环境会重置运行进程。”前半句是硬条件，后半句是代价——换环境等于重启运行进程，正在跑的任务会被打断。
改完点右下角应用环境；点取消或者右上角 ×，改动不生效。环境必须有可用的 Polars；要用 pandas，得在同一个解释器里装好 pandas。
扫描到底扫了什么？注册表、PATH、Python 启动器，以及常见的 Python 和 Conda 目录。列表里每个环境都会显示它自己的 Python、Polars、pandas 版本，还有可不可用。
没扫到你要的？点“重新扫描”，或者用“浏览选择…”，再或者直接把虚拟环境的 python.exe 完整路径粘进去。下拉框支持方向键、Enter 和 Esc。
点应用之前它会校验解释器和 Polars。缺库或识别不了，先把那个环境修好，再回来重新扫描。还有个容易吃亏的认知：列表里的版本不代表你另一个终端、另一个虚拟环境里的版本。
三种执行模式，区别在“Python 在哪跑”
外部兼容
每本工作簿一个独立的 Python worker 进程。同一工作簿里的任务串行跑，数据经进程间 JSON 传递。适合：已有环境要沿用、想要工作簿之间的进程隔离、需要更容易地强制停止。停止、超时或崩溃之后，下次运行重建 worker。
内嵌高性能
跑在宿主进程内的 CPython 里。省掉外部进程那段 JSON，Excel 内嵌结果走 Arrow C Data 直接转进原生结果网格。面向通过资格检查的环境和较大的数据处理。代价是不同工作簿共享同一个解释器和模块状态（任务仍然串行）。
自动选择
跑用户代码之前，先判断是否符合内嵌条件，符合就走内嵌，否则走外部。判断依据是版本、桥接器、文件指纹和已绑定环境——不是按数据量，也不是按实时速度。脚本失败、超时或取消之后，它不会换条路线再执行一遍。
两个特别容易误解的点，单独拎出来说：
每次脚本用的是新的变量空间，但内嵌环境的模块状态活着。你 import 进来的库、建过的扩展对象，可能比这一段脚本活得更久。所以别指望“内嵌里每次都是干净的世界”。
内嵌不是任意 Python 版本都能用。当前资格范围是：Windows x64、带 GIL 的 CPython 3.13.7 或 3.15.0，搭配 Polars 2.0.0 或 2.1.0。环境一旦绑定，换解释器或者换 CPython 版本，通常需要重启宿主。不在范围内，老老实实用外部兼容。
高性能入口管的是另一件事
很多人把这两个开关当同一个，其实分工很干净：
执行模式 = Python 在哪跑。高性能入口 = 公式结果怎么回 Excel。
外部兼容 + 不勾 外部 Python → JSON → .NET Excel 数组。传统返回路径，排查兼容问题时用这条。
外部兼容 + 勾 外部 Python → JSON → 原生结果网格 → Excel。注意：仍然是外部进程，仍然有 JSON，不会因此变成内嵌，也不会变成 Arrow。
内嵌高性能 + 勾 同进程 CPython → Arrow C Data → 原生结果网格 → Excel。这是完整的那条快路。
自动选择 运行前决定走内嵌还是外部，然后使用对应的返回路径。
三条规矩得记牢：
这个勾选框只在 Excel 界面显示，改完必须关掉 Excel 重启才生效。
关掉它并重启后，原生桥接器不加载：强制内嵌不可用，自动选择会自动退回外部。
界面上选内嵌或自动时，入口会自动勾上。另外——别把 Excel 这套返回机制套到 WPS 上，WPS 没有同一组入口，它的公式返回方式跟 Excel 有差别。
执行超时：60 秒是默认，不是建议
范围 1 到 86400 秒，默认 60。它限制的是任务执行的等待时间：外部文件读取卡住、意外写了长循环、算得比预想久，到点就掐，不用你干等。合理的长任务，把它调大就行。
两个“耗时”不是一个东西。内嵌任务在等待队列里排的时间，不计入 Python 执行超时；而状态栏那个“公式耗时”，包含依赖分析、传输、排队和宿主展开全过程。所以这两个数字不能拿来做性能对比。
超时和停止都会撤销结果交付。外部 worker 会被结束，下次运行重建；内嵌 Python 能在可中断的位置响应取消，但正在跑的本机扩展调用不保证立刻强杀，界面可能短时间显示“资源仍在退出”。
最要紧一句：超时撤不掉脚本已经产生的副作用。文件写进去了、数据库改了，都收不回来。
四个按钮，别点错
它们长得都像“运行”，行为差得很远。
执行写入（Ctrl+Enter）
在当前编辑单元格写入 =PYXL(“Python 代码”) 并计算，结果按宿主动态数组机制展开，代码保存在公式里。适合：结果要随输入变化重算，或者以后还想在公式栏和 PyXL 里继续改。
预览（Ctrl+Shift+Enter）
运行代码，结果只在侧栏显示，不写工作表。默认先看 Python 文本，可切表格视图。开发、检查内容、看尺寸和输出目标时用它。脚本真的会执行，文件和网络的副作用不会因为“只是预览”就消失。
执行一次
计算完整结果，写成普通单元格值，不生成自动重算公式。可用 target 指定单个起点。覆盖已有内容或公式前会提示确认。成功后，未绑定公式的当前代码和草稿会被清空。
停止
停止本工作簿计算并撤销结果交付，内嵌的本机调用可能还会退出几秒。同样撤不掉已经产生的外部副作用。
“执行一次”其实很谨慎。它先完整转换，再检查工作表边界、保护、合并区域、已有内容和公式；你确认覆盖之后，直接用这次的结果写入，不会偷偷重跑一遍脚本。等待确认期间目标内容被改动，会要求你重新确认。公式展开的位置被占用，由宿主报溢出错误。
还有个常被问的：打开工作簿不会因为打开了这个窗格就重跑脚本。自动计算时，是输入变化触发更新；切到手动计算，按 F9，异步跑完之后可能还需要再按一次 F9。
公式模式还有个硬限制：xl.read 的引用必须是直接写出来的静态字符串。xl.read(address)、循环拼出来的字符串、xl.read() 空参数，这些在预览和执行一次里都能跑，但生成不了公式。
为什么预览能算，写进单元格却报错
图 3 目标越界时红字报错，Python 文本照样可看。
图上那行代码把结果写向 XFD1048576，也就是 Excel 的最后一个单元格，两列数据往右一放就出去了。
这张图说明了它的分层：目标检查失败，不影响你看 Python 文本。侧栏是侧栏，工作表是工作表。算出来的东西永远看得见，写不写得进去是另一回事。
保存和草稿：代码不会自己进文件
编辑器里按 Ctrl+S，或者点侧栏的保存，它做三件事：同步当前脚本草稿 → 核对其他窗格 → 保存工作簿文件。
注意它不执行代码，也不会把“未写入”的代码变成 PYXL 公式。已有公式的代码跟着工作簿走；没写入的代码，作为那个单元格的草稿存在工作簿里。新工作簿请先用宿主“另存为”选好位置。
Excel/WPS 自己的保存和另存为，保存的是整个工作簿（包含已同步的草稿和公式），不是单独一个 .py 文件。它也会校验最新草稿，提示“草稿未同步”或“保存未完成”，就按提示继续编辑并重试。
两者区别只有一句：侧栏保存明确先同步当前草稿，再发起工作簿保存；都不是“执行写入”。
切换单元格时，三个选择提示会出现
图 4 切换单元格时的草稿提示与三个选项。
你在编辑器里改了代码、还没点执行写入，转头点了工作表里另一个单元格，就弹出提示：“已选中 '汇总'!$B$1，正在编辑 '汇总'!$A$1 的未写入草稿。请选择是否保留草稿并切换单元格。”下面三个选项，就是让你决定这份草稿怎么处理。
保留不切换
草稿存进工作簿的草稿记录，宿主把你送回原来的编辑单元格，侧栏继续显示原代码。误点了别人单元格，或者还要接着改，用这个。
保留并切换
原单元格的草稿留着，切到新单元格，并加载那里的代码或草稿；以后选回原单元格能恢复。在单元格 A 写到一半要去看单元格 B，选它。
不保留并切换
清掉原单元格的自动保存草稿，然后切过去。以后回到原单元格，恢复它原有的 PYXL 公式代码；如果原单元格本来没公式，编辑器就是空的。它只清草稿，不等于删除原单元格已有的公式。
跟着图 4 做一次：在 A1 里写 xl.write(42)，先别点执行写入，直接点 B1。出现提示后选“保留并切换”。这时 B1 成了编辑目标；再点回 A1，刚才的草稿就回来了。如果 B1 自己也有未写入改动，先处理 B1 的提示。想继续留在 A1 就选“保留不切换”；确定不要 A1 的草稿，才选“不保留并切换”。
草稿按工作簿 + 单元格分别记录。保留草稿不会执行代码，也不会写成公式；预览过的代码依然是未写入草稿，切换时照样提示。
真正要记的是：草稿记录不等于工作簿已保存。关之前用侧栏保存或宿主保存，并确认保存完成；新建工作簿先另存为；关的时候选“不保存”，没进文件的草稿就会丢。没有未写入改动时通常可以直接切换，运行或切换处理中也可能短暂提示，等任务结束再操作。
格式化，和“不用手打单元格地址”
格式化按 Shift+Alt+F，或点“格式化”。用的是本地运行的 Ruff WebAssembly，代码不上传。当前配置：每级缩进 4 空格、目标行宽 88、保留你原来的引号风格。语法不完整会提示失败并保留原文；格式完可以用 Ctrl+Z 撤销。它只整理排版，不管业务逻辑对不对。
图 5 光标停在 xl.read() 空参数位即可框选。
手打 '订单 明细'!A1:D100 这种地址，一容易打错，二容易漏引号。两个办法躲开它：
办法一，按钮：先在工作表里选好放结果的目标格，再打开或编辑 PyXL；点插入选区，在宿主弹出的选区窗口里选输入区域（可跨表、按 Ctrl 选多块）；确认后回到原目标格并插入引用。
光标在 xl.read(...) 括号里，就插区域参数；在函数外，就插完整读取语句。再点一次能追加区域；取消则保留原代码并回到目标格。
办法二，直接框选（就是图 5）：把光标放到 xl.read() 第一个空的区域参数位置，直接去工作表里框。要追加，先在已有引用后面打个逗号，把光标移到新的空参数位，再框。
关键字参数的位置、已有引用字符串的内部，不会触发直接框选——这是保护，不是 bug。按 Esc 或点“取消框选”退出。表名带空格要用单引号，自动插入会帮你处理引用格式。
xl.read：读工作表
xl.read(*refs,headers=True, dataframe="polars", schema=None)
xl 由 PyXL 提供，读取当前工作簿里的值，返回 DataFrame。
*refs
一个或多个区域引用。一个引用返回一个 DataFrame，多个按顺序返回元组，不会拼接。
headers
True 第一行作列名；False 所有行都是数据，列名自动生成 column_1 等。空表头自动命名，重复表头加 _1、_2。
dataframe
默认 “polars”；设成 “pandas” 返回 pandas DataFrame，要求当前环境装了 pandas。
schema
用字典指定部分列的类型；没指定的列继续自动推断，列顺序不变。列名不存在或无法转换时报错。它排在 dataframe 之后，因为类型候选跟着 dataframe 走——先定 polars 还是 pandas，编辑器才知道该给 pl.Float64 还是 “Int64”。
*refs 能吃五种引用，这是它比手写范围爽的地方：
普通区域 "A1:C10"；带空格的表 "'订单 明细'!A1:D100"；命名区域 "销售数据"；Excel 表 "订单表[#All]"；溢出引用 "结果!A1#"。
import polars as plorders = xl.read("订单!A1:C100",schema={"金额": pl.Float64},)xl.write(orders)
# 一次读两个区域，按顺序解包；不自动合并orders, customers = xl.read("订单表[#All]","客户表[#All]",dataframe="pandas",)# 无表头；列名从 column_1 开始raw = xl.read("A1:C10",headers=False,schema={"column_2": pl.Float64},)
不传引用的时候：预览和执行一次，读的是你点击运行那一刻的选区，多块区域返回元组；执行写入必须用静态字符串引用。多个引用的结果各自独立，不会自动拼；共用的 schema 会分别作用到每个区域——两个区域结构不同，就分开读。
schema 的键，是处理后的列名，大小写和空格都得对上；只列需要转的列。Polars 用自身 dtype，比如 pl.Float64；pandas 用字符串，比如 "Int64"、"string"。要支持缺失值的整数，用大写的 “Int64”。空字典和 None 都表示全部自动推断。
可空整数 pl.Int64 / "Int64"小数 pl.Float64 / "Float64"文本 pl.String / "string"布尔 pl.Boolean / "boolean"
# pandas：编号保留文本前导零，数量允许缺失orders = xl.read("订单!A1:C100",dataframe="pandas",schema={"编号": "string", "数量": "Int64"},)
转换走的是各库自己的类型语义，不保证无损；不匹配或转不了会报错。schema 在编辑器里有补全，能直接插模板和类型。
读的是公式的计算值。Excel 日期仍然是序列数，得按工作簿的日期系统显式转换。Polars 的空白是 None，pandas 按类型用缺失值；数字和文本混在一列，可能被推断成文本。单元格里有错误会报告位置。单元格内的原生 List、嵌套数组，暂时不支持。
最后提醒一个特别冤的：单元格里显示 00123，值其实是数字 123，光把它转成字符串变不回 00123——前导零是显示格式，不是数据。真需要保留，就得靠 schema 指定文本类型去读原始文本列，而不是读完了再转。
xl.write：写回工作表
xl.write(data, target=None, *, headers=True, transpose=False)
data
必填。Polars/pandas 的 DataFrame、Series、标量，或各行等长的二维列表。普通一维列表不行，请写成 [[1], [2]] 或 Series。
target
默认当前编辑单元格。仅“执行一次”可以指定，且只能是当前工作簿的单个起点，如 “结果！B2”，不能写 “B2:D10” 这种区域。公式模式不能指定 target。
headers
输出 DataFrame 列名或 Series 名称。对标量和二维列表不起作用，不会给你加表头。
transpose
True 时先处理表头，再转置整个结果。headers 和 transpose 必须以关键字传入，值必须是布尔值。
xl.write(42) # 单个值result = pl.DataFrame({"地区": ["华东", "华南"], "金额": [100, 200]})xl.write(result, headers=True, transpose=True)# 两行：地区 / 华东 / 华南；金额 / 100 / 200
# 仅用于"执行一次"；预览只检查目标，不实际写入xl.write([["地区", "金额"], ["华东", 100]],target="'汇总 表'!B2",)
每次执行最多调用一次 xl.write，返回值是 None。调用时先把要输出的数据冻结，脚本成功结束才提交，后面报错就不提交这次结果。没调用的话，最后一个顶层表达式作为结果；什么都没有输出，就是空字符串。预览能看 Python 表达形式，但不保证那个对象能转成工作表单元格。
几个常被抱怨的细节，一次说清：pandas 的行索引不输出，要分组键先 reset_index()；MultiIndex 列名得先转成普通字符串列名，或者用 headers=False；日期时间对象输出成 ISO 文本；超过 15 位精度的整数按文本输出；以 = 开头的字符串也当文本；pandas 缺失值输出空白；转不了的对象、NaN 以外的无穷大之类会报错；Decimal 会转成数字并设置小数位格式，可能损失精度，要精确值先转文本。
补全：两种候选最值得用
编辑区是 Monaco，行号、缩进、语法高亮都有，颜色跟着 Excel/WPS 主题走。补全靠 basedpyright，由 Node.js 22 以上起的语言服务提供——它只是补全服务，不是执行 Python 的解释器，这俩别搞混。
图 6 逗号后 Ctrl+Space 列出未填参数与默认值。
图上候选把默认值和用途都写了出来。这就是“不用背参数”的正确姿势：写到逗号停一下，按 Ctrl+Space 看它列。
图 7 默认 polars，schema 冒号后给出 pl.* 类型候选。
注意第三行那句“保留文本中的前导零”——前提是列本来就是文本。前面说的“123 救不回 00123”，说的就是列已经是数字的情况。两句话不矛盾，是链路上前后两个位置。
其余补全规则，一并放这：输入 pl.、df. 这类成员访问会列候选；函数或方法补全会自动补括号、把光标放在参数位，已经有括号就不重复插；输入 ( 、逗号或参数名前缀，会显示还没填的合法参数、类型和默认值，选中可插入可编辑的值；嵌套调用优先提示最内层；类型推不出来就退回普通补全。
换过 Python 之后，记得确认补全针对的是实际生效的那个环境。补全是静态辅助：不保证运行一定成功，动态生成的成员也可能推不全，它也不等于“帮你装依赖”。
结果、输出、问题：三个标签各管一件事
底部默认三个标签。主动运行后面板展开，关掉只是折叠。右侧那个刷新图标有区别：结果和输出的刷新会重跑当前代码的侧栏预览，副作用可能再来一次；问题标签的刷新只是重新请求诊断，不执行脚本。
图 8 结果的两个视图：Python 文本、Excel 表格。
Python 文本展示的是 repr() 的结果，可以带上 print() 的输出，适合看元组、字典、集合、类型对象和调试文本；None 不显示；最多 200000 字符，超了会提示截断。
Excel 表格是可转换结果按单元格排列后的预览。侧栏最多显示前 101 行、50 列，但完整尺寸照样标着，实际展开或执行一次用的是完整结果。横竖都能滚。有些对象转不了，表格视图会说明原因，而 Python 文本那边你照样能看。
再说一遍图 3 那件事：这是预览，不代表已经写进工作表。
图 9 运行错误在“输出”标签，状态栏同步提示。
输出装的是运行时信息：print()、警告、异常和 traceback。写个 print("已读取", len(df)) 看进度就挺有用。执行失败先看错误类型和行号。print 不会把值写进单元格——那是 xl.write 的事。
图 10 静态诊断在“问题”标签，点条目可跳转。
问题是语言服务给的静态诊断：语法、类型、参数用它。点某条能跳到对应行。它可能包含警告，不一定意味着执行必然失败；真要查运行错误还是看“输出”。补全服务没就绪时，诊断可能不完整。
状态栏：四个数字别读错
看回图 1 最底下一行：“运行完成 · 28 ms”｜“表格 3 行 × 2 列”｜“公式耗时 —”｜“代码补全已就绪”。四块，从左到右：
操作状态。准备、运行中（带旋转图标）、运行完成及耗时、已写入位置、停止、格式化成功/失败、草稿或保存提示、环境及运行错误，都以当前操作的文字为准。
表格尺寸。“表格 3 行 × 2 列”是完整输出展开后的尺寸，包含输出表头，按转置后的方向统计，不受侧栏预览截断或折叠影响。失败或无法转换时不显示。
公式耗时。当前单元格公式从计算开始到宿主数组展开完成的时间，含依赖分析、传输、排队与展开。鼠标停上去能看到 Python 执行和结果转换各占多少。显示“计算中…”、失败或停止时会标注；还没计时显示 —；走缓存复用会保留上次的耗时。
补全状态。“代码补全已就绪”，或连接中、异常。它只说明语言服务可不可用，不代表 Python 脚本跑过了。
显示规则：公式耗时小于 1 秒按毫秒写，小于 1 毫秒写 <1 ms，再长按秒写。操作状态里的运行耗时和公式耗时统计范围不同，不能直接拿来比性能。
快捷键：先点进编辑区再按
Ctrl+Enter 执行写入公式Ctrl+Shift+Enter 预览Ctrl+S 同步草稿并保存工作簿Shift+Alt+F 格式化全部代码Ctrl+Space 手动触发补全Ctrl+/ 切换选中行或当前行注释Ctrl+Z / Ctrl+Y 撤销 / 重做Ctrl+F / Ctrl+H 查找 / 替换Ctrl+A C X V 全选、复制、剪切、粘贴Esc 关闭提示或取消直接框选
宿主、键盘布局或系统级快捷键可能抢掉个别组合，按不动就点按钮。编辑区右键菜单里有剪切、复制、粘贴、更改所有匹配项和命令面板。
最后一个细节，Windows 路径建议写成原始字符串：r"C:\Users\name\data.xlsx"。不然 \n、\t 会被当成转义字符，路径莫名其妙就错了。
最后：一个完整的最小闭环
假设“订单”表 A1:C4 是表头“地区、商品、金额”加三行数据。新建或选中“汇总”表的 A1：
import polars as plorders = xl.read("订单!A1:C4",schema={"金额": pl.Float64},)summary = (orders.group_by("地区").agg(pl.col("金额").sum().alias("合计")).sort("地区"))xl.write(summary)
先点预览，看 Python 文本和 Excel 表格对不对；需要随订单数据更新就点执行写入，并确保输出区域有足够空位；只要一份静态结果就点执行一次，按提示确认覆盖；最后保存工作簿。
要输出 pandas 的分组键，记得 reset_index()；要读更多行，改引用范围，或者换成 Excel 表引用。
Excel 和 WPS 不是不能用 Python，是以前没有一条顺路。现在这条路很短：选中单元格 → 写代码 → Ctrl+Enter。
你现在最想用 Python 替掉哪个重复操作？评论区说说，我挑几个写成下一篇教程。
