pandas 安装完全指南:conda-forge、pip、源码构建与依赖体系详解
pandas 安装完全指南:conda-forge、pip、源码构建与依赖体系详解
本指南以 pandas 官方安装文档 doc/source/getting_started/install.rst 为主体,系统讲解 pandas 的四种安装路径(conda-forge、PyPI/pip、源码构建、每日开发版)、Python 版本支持策略、测试套件运行方式,以及完整的必需依赖与可选依赖(pip extras)体系。读完本文,你将能根据自身环境(数据分析新手、PyData 栈用户、库作者或 pandas 贡献者)选择最合适的安装方式,并理解各可选依赖与 pandas.read_* / DataFrame.to_* 系列方法之间的对应关系,以及版本约束在 pyproject.toml 与 pandas/compat/_optional.py 中的落地实现。
官方分发渠道概览
pandas 开发团队正式分发 pandas 的渠道有三个:
- conda-forge:配合 conda 包管理器安装,命令为
conda install -c conda-forge pandas; - PyPI:配合 pip 包管理器安装,命令为
pip install pandas; - 源码分发:从 GitHub 上的 pandas 官方仓库克隆源码后自行构建安装。
注意:pandas 也可能通过上述渠道以外的其他来源安装,但这些来源不由 pandas 开发团队管理,无法保证版本同步与质量。
这一渠道格局也直接反映在仓库的构建与依赖配置中:pyproject.toml 的 <a href="https://link.gitcode.com/i/c76f09bb906532db6c45874168384fe2" target="_blank">build-system] 使用 meson-python 作为构建后端(build-backend = "mesonpy"),requires-python = '>=3.11',确保以 PyPI 分发构建出的 wheel 与 conda-forge 构建结果行为一致;而 [pixi.toml 中 channels = ["conda-forge"] 则印证了 conda 生态统一走 conda-forge 通道。
Python 版本支持
pandas 对 Python 版本的支持遵循其 版本与支持政策 中的 policies.python_support 一节(即 SPEC 0 指南)。从当前仓库的打包元数据看,pyproject.toml 声明 requires-python = '>=3.11',classifiers 覆盖 Python 3.11~3.15,即当前版本最低支持 Python 3.11。
关于版本号本身,pandas 采用宽松的语义化版本(MAJOR.MINOR.PATCH)策略:破坏性 API 变更只出现在 major 版本,deprecation 在 minor 版本引入并在下一个 major 版本强制执行,patch 版本不引入新的 deprecation。这对"该装哪个版本"有直接指导意义:生产环境应选择最新的 patch/minor 稳定版,尝鲜新特性则使用下一节介绍的最新开发版。
方法一:使用 conda 安装
对于使用 conda 包管理器的用户,pandas 从 conda-forge 通道安装:
conda install -c conda-forge pandas
安装 conda 包管理器本身,官方推荐使用 Miniforge 发行版(同时支持 Linux、macOS 与 Windows)。
官方同时建议在虚拟环境中安装和运行 pandas,避免污染基础环境,也避免不同项目间的依赖冲突:
conda create -c conda-forge -n name_of_my_env python pandas
conda activate name_of_my_env
其中 name_of_my_env 是你要创建的环境名,python 与 pandas 会由 conda 一并解析版本并安装。
对于 Python 新手,最省事的入门方式是安装 Anaconda 发行版:它是一个跨平台(Linux、macOS、Windows)的面向数据分析与科学计算的 Python 发行版,会自动带上 Python、pandas 以及 PyData 栈中的 SciPy、NumPy、Matplotlib 等常用包。需要留意的是,Anaconda 内置的 pandas 并非由 pandas 开发团队官方管理,其版本可能滞后于 conda-forge 或 PyPI 上的最新版。
补充:仓库中基于 conda-forge 的完整依赖清单可以参考根目录 environment.yml(CI 与开发环境用)和 pixi.toml(基于 pixi 的开发工作区定义),它们与安装文档共同维护着同一套版本约束。
方法二:使用 pip 安装
对于使用 pip 包管理器的用户,pandas 从 PyPI 安装:
pip install pandas
pandas 还支持通过 extras(方括号语法)一次性安装若干可选依赖以启用特定功能。例如,要启用读取 Excel 文件所需的可选依赖:
pip install "pandas[excel]"
所有可用的 extras 列表见后文"可选依赖"各节。全部可选依赖可以通过 pandas[all] 一键安装。
官方同样建议使用虚拟环境,例如 Python 标准库自带的 venv:
python -m venv myenv
source myenv/bin/activate # Windows 下为 myenv\Scripts\activate
pip install pandas
extras 的仓库级定义
这些 extras 并非文档中的"概念",而是实实在在地定义在 pyproject.toml 的 [project.optional-dependencies] 段中。例如文档提到的 pandas[excel] 对应:
excel = ['odfpy>=1.4.1', 'openpyxl>=3.1.5', 'python-calamine>=0.4.0', 'pyxlsb>=1.0.10', 'xlrd>=2.0.2', 'xlsxwriter>=3.2.5']
而 pandas[all] 则是把所有 extras(含 test)合并后的完整集合。这意味着你可以在 requirements.txt 或 pyproject.toml 中以 pandas[performance, aws] 的形式声明项目依赖,pip 会自动解析对应版本约束。
方法三:从源码安装
从源码构建 pandas 的完整指引见 贡献指南,若需要搭建可修改代码的开发环境,则参考 创建开发环境。
简要来说,源码构建需要:C/C++ 编译器(Windows 使用 Visual Studio Build Tools,macOS 使用 xcode-select --install,Linux 一般随系统自带)+ Python 环境 + 构建工具链。当前仓库的构建系统以 meson 为核心:
- pyproject.toml 的
[build-system]声明了meson-python>=0.19.0,<1、meson>=1.2.3,<2、Cython>3.1.0,<4、numpy>=2.0.0等构建期依赖; - meson.build 定义了整个项目的编译目标(包括
pandas/_libs下的 Cython 扩展模块)。
典型流程是克隆仓库后执行:
git clone <pandas 官方仓库地址>
cd pandas
python -m pip install -e . --no-build-isolation # 可编辑安装,便于开发调试
源码构建主要面向两类人群:想要为 pandas 提交代码的贡献者,以及需要特定编译选项(如 sanitizer、不同 numpy 版本矩阵)的高级用户;普通数据分析场景推荐直接使用 conda 或 pip 的预编译 wheel。
安装开发版本(每日最新版)
安装开发版本是以下两种需求的最快路径:
- 尝鲜将在下一个正式版本中发布的新特性(即刚合入 main 分支的 pull-request 内容);
- 验证你遇到的 bug 是否已在最近一次发布之后被修复。
pandas 的开发版本通常每天发布一次,托管在 anaconda.org 的 scientific-python-nightly-wheels 索引上(即 PyPI 生态中的 nightly wheel 源)。安装命令:
pip install --pre --extra-index-url https://pypi.anaconda.org/scientific-python-nightly-wheels/simple pandas
--pre 允许 pip 接受预发布版本,--extra-index-url 将 nightly 索引作为额外源;pandas 开发团队也会将该索引用于其依赖(如 numpy、pyarrow)的 nightly 测试,见 pixi.toml 中的 numpy-nightly 与 pyarrow-nightly feature 定义。
注意:安装开发版前,可能需要先卸载已存在的 pandas 版本:
pip uninstall pandas -y
运行测试套件
如果 pandas 是通过源码方式安装的,在仓库根目录执行 pytest pandas 即可运行全部单元测试。
也可以不进入源码目录,直接从 pandas 模块本身运行测试:pd.test()。该入口定义在 pandas/util/_tester.py 中,其行为要点如下:
- 默认以
-m "not slow and not network and not db"筛选标记,跳过慢速、联网与数据库相关用例; - 可通过
extra_args传入自定义 pytest 参数; - 传入
run_doctests=True时,只运行 Python 与 Cython 文档字符串示例测试; - 运行前会通过
import_optional_dependency("pytest")检查 pytest 是否可用。
运行测试所需的依赖可以通过 extras 安装:
pip install "pandas[test]"
对应 pyproject.toml 中的 test = ['pytest>=8.3.4', 'pytest-xdist>=3.6.1']。
注意:测试失败并不一定说明 pandas 安装有问题——部分用例依赖特定平台能力(如剪贴板)、可选依赖或外部服务,在精简环境下失败属正常现象。
依赖体系
必需依赖(Required dependencies)
pandas 的运行必需以下依赖:
| 包 | 最低支持版本 | 说明 |
|---|---|---|
| NumPy | 2.0.2 | 底层数组与数值计算基础 |
| python-dateutil | 2.9.0 | 日期时间解析与工具 |
| tzdata * | / | 时区数据库(仅 Windows 和 Pyodide/Emscripten 需要) |
* tzdata 仅在 Windows 与 Pyodide(Emscripten)平台需要。
这一约束在 pyproject.toml 的 dependencies 段中有精确对应,还带上了平台条件标记:
dependencies = [
"numpy>=2.0.2; python_version < '3.14'",
"numpy>=2.3.3; python_version >= '3.14'",
"python-dateutil>=2.9.0",
"tzdata; sys_platform == 'win32'",
"tzdata; sys_platform == 'emscripten'",
]
版本策略上,必需依赖的最低支持版本大约为 pandas major/minor 版本发布时间的 2 年前。源码中版本号的唯一权威维护点在 pandas/compat/_optional.py 的 VERSIONS 字典——该文件顶部注释明确要求"更新版本时同步修改 install.rst、pixi.toml、deps_minimum.toml 与 pyproject.toml",说明安装文档中的每个版本号都与运行时代码严格对应。
可选依赖(Optional dependencies)机制
pandas 有大量可选依赖,它们只在特定方法被调用时才被使用。例如:
pandas.read_hdf需要pytables包;DataFrame.to_markdown需要tabulate包。
如果调用这些方法时对应依赖未安装,pandas 会抛出 ImportError。这一行为由 pandas/compat/_optional.py 的 import_optional_dependency() 统一实现:它默认在依赖缺失时抛出带友好提示信息的 ImportError,在版本过旧时同样报错;此外还维护了 INSTALL_MAPPING,用于处理"导入名与 PyPI 包名不一致"的情况(如 bs4 → beautifulsoup4、tables → pytables、python_calamine → python-calamine)。
用 pip 安装可选依赖有两种方式:作为 extras 声明(如 pandas[performance, aws]),或写入 requirements.txt / pyproject.toml 依赖文件。pandas[all] 可安装全部可选依赖。可选依赖的最低支持版本大约为 pandas 版本发布时间的 1 年前;更老版本可能仍能工作,但未经测试、不受支持。
下文按功能分组列出全部 extras 及其版本约束(均与 pyproject.toml 的 [project.optional-dependencies] 一致)。
性能依赖(推荐安装)
pip install "pandas[performance]"
官方强烈鼓励安装这些库,尤其是在处理大数据集时,它们能带来显著的性能提升:
| 依赖 | 最低版本 | pip extra | 作用 |
|---|---|---|---|
| numexpr | 2.11.0 | performance | 利用多核以及智能分块、缓存加速特定数值运算 |
| bottleneck | 1.5.0 | performance | 通过专门的 Cython 例程大幅加速特定 nan 处理运算 |
| numba | 0.61.2 | performance | 支持 engine="numba" 的运算:基于 LLVM 的 JIT 编译器把 Python 函数翻译为优化后的机器码 |
其中 numexpr 与 bottleneck 主要作用于 DataFrame / Series 的归约与元素级运算路径(可参考 pandas/core/array_algos/masked_reductions.py、pandas/core/nanops.py 中的加速分支);numba 则作为 groupby 等方法 engine="numba" 参数的备选执行引擎(见 pandas/core/_numba 目录)。
可视化与输出格式化
pip install "pandas[plot, output-formatting]"
| 依赖 | 最低版本 | pip extra | 作用 |
|---|---|---|---|
| matplotlib | 3.10.5 | plot | 绘图库 |
| Jinja2 | 3.1.6 | output-formatting | DataFrame.style 的条件格式化模板渲染 |
| tabulate | 0.9.0 | output-formatting | 以 Markdown 友好格式打印(配合 DataFrame.to_markdown) |
计算(Computation)
pip install "pandas[computation]"
| 依赖 | 最低版本 | pip extra | 作用 |
|---|---|---|---|
| SciPy | 1.16.1 | computation | 各类统计函数(如分位数插值、稀疏矩阵相关运算) |
| xarray | 2025.7.1 | computation | 面向 N 维数据的 pandas 风格 API,用于 DataFrame.xarray 双向转换 |
Excel 文件
pip install "pandas[excel]"
| 依赖 | 最低版本 | pip extra | 作用 |
|---|---|---|---|
| xlrd | 2.0.2 | excel | 读取 .xls 文件(已弃用,建议改用 python-calamine) |
| xlsxwriter | 3.2.5 | excel | 写入 .xlsx 文件 |
| openpyxl | 3.1.5 | excel | 读写 Excel 2010 的 .xlsx/.xlsm/.xltx/.xltm 文件 |
| pyxlsb | 1.0.10 | excel | 读取 .xlsb 文件(已弃用,建议改用 python-calamine) |
| python-calamine | 0.4.0 | excel | 读取 .xls/.xlsx/.xlsm/.xlsb/.xla/.xlam/.ods 文件 |
| odfpy | 1.4.1 | excel | 读写 OpenDocument 1.2 文件(.odf/.ods/.odt) |
这些引擎在运行时由 pandas/io/excel 目录下的读写器按扩展名选择默认引擎(参见 pandas/io/excel/_util.py 的 get_default_engine),缺少对应引擎时同样通过 import_optional_dependency 报错并给出安装提示。
HTML 表格解析
pip install "pandas[html]"
| 依赖 | 最低版本 | pip extra | 作用 |
|---|---|---|---|
| BeautifulSoup4 | 4.13.4 | html | read_html 的 HTML 解析器 |
| html5lib | 1.1 | html | read_html 的 HTML 解析器 |
| lxml | 6.0.0 | html | read_html 的 HTML 解析器 |
顶层函数 pandas.read_html 需要以下解析器组合之一:
- BeautifulSoup4 + html5lib;
- BeautifulSoup4 + lxml;
- BeautifulSoup4 + html5lib + lxml;
- 仅 lxml 也可以,但建议阅读 HTML 表格解析注意事项 中
io.html.gotchas一节,了解为何通常不建议只装 lxml。
警告:
- 如果安装了 BeautifulSoup4,则必须同时安装 lxml 或 html5lib(或两者都装)。只装 BeautifulSoup4 时
read_html无法工作。- 强烈建议阅读上述
io.html.gotchas章节,其中解释了这三个库的安装与使用中的坑点。
XML
pip install "pandas[xml]"
| 依赖 | 最低版本 | pip extra | 作用 |
|---|---|---|---|
| lxml | 6.0.0 | xml | read_xml 的 XML 解析器、to_xml 的树构建器 |
SQL 数据库
传统驱动可安装:
pip install "pandas[postgresql, mysql, sql-other]"
| 依赖 | 最低版本 | pip extra | 作用 |
|---|---|---|---|
| SQLAlchemy | 2.0.42 | postgresql, mysql, sql-other | 除 sqlite 之外数据库的 SQL 支持 |
| psycopg2 | 2.9.10 | postgresql | PostgreSQL 的 SQLAlchemy 引擎 |
| pymysql | 1.1.1 | mysql | MySQL 的 SQLAlchemy 引擎 |
| adbc-driver-postgresql | 1.7.0 | postgresql | PostgreSQL 的 ADBC 驱动 |
| adbc-driver-sqlite | 1.7.0 | sql-other | SQLite 的 ADBC 驱动 |
其他数据源
pip install "pandas[hdf5, parquet, iceberg, feather, spss, excel]"
| 依赖 | 最低版本 | pip extra | 作用 |
|---|---|---|---|
| PyTables | 3.10.2 | hdf5 | 基于 HDF5 的读写 |
| zlib | / | hdf5 | HDF5 的压缩支持 |
| fastparquet | 2024.11.0 | - | Parquet 读写(默认引擎为 pyarrow) |
| pyarrow | 16.0.0 | parquet, feather | Parquet、ORC、feather 的读写 |
| PyIceberg | 0.9.1 | iceberg | Apache Iceberg 的读写 |
| pyreadstat | 1.3.0 | spss | 读取 SPSS 文件(.sav) |
| odfpy | 1.4.1 | excel | OpenDocument 格式(.odf/.ods/.odt)读写 |
警告(ORC):
- 若使用
pandas.read_orc,强烈建议用 conda 安装 pyarrow。pyarrow 若从 PyPI 安装,read_orc可能失败,且read_orc不兼容 Windows 系统。
云存储访问
pip install "pandas[fss, aws, gcp]"
| 依赖 | 最低版本 | pip extra | 作用 |
|---|---|---|---|
| fsspec | 2025.7.0 | fss, gcp, aws | 处理本地与 HTTP 之外的各类文件系统(s3fs、gcsfs 的必需依赖) |
| gcsfs | 2025.7.0 | gcp | Google Cloud Storage 访问 |
| s3fs | 2025.7.0 | aws | Amazon S3 访问 |
剪贴板
pip install "pandas[clipboard]"
| 依赖 | 最低版本 | pip extra | 作用 |
|---|---|---|---|
| PyQt5 | 5.15.11 | clipboard | 剪贴板 I/O(read_clipboard / DataFrame.to_clipboard) |
| qtpy | 2.4.3 | clipboard | 剪贴板 I/O |
注意:根据操作系统不同,可能还需要安装系统级软件包。在 Linux 上使用剪贴板功能,系统需安装命令行工具
xclip或xsel之一。
压缩
pip install "pandas[compression]"
| 依赖 | 最低版本 | pip extra | 作用 |
|---|---|---|---|
| Zstandard | 0.23.0 | compression | Zstandard 压缩 |
时区
pip install "pandas[timezone]"
| 依赖 | 最低版本 | pip extra | 作用 |
|---|---|---|---|
| pytz | 2020.1 | timezone | 替代标准库 zoneinfo 的时区库 |
版本约束的统一维护
值得注意的是,本文档中所有依赖的最低版本号并非"文档独有",而是与源码中的单一事实来源同步维护的。仓库里存在三处需要保持一致的地方:
- pyproject.toml 的
dependencies与[project.optional-dependencies]——pip 安装时的硬约束; - pandas/compat/_optional.py 的
VERSIONS字典——运行时import_optional_dependency()校验的版本底线(如"python-calamine": "0.4.0"、"tables": "3.10.2"),其INSTALL_MAPPING还负责导入名到发行包名的翻译; - pixi.toml 与 environment.yml——conda/pixi 开发环境的依赖矩阵。
因此,当你通过 pip install "pandas[excel]" 或 conda install -c conda-forge pandas 安装后,若某个 read_* 方法因缺依赖抛出 ImportError,其提示信息中的安装建议与上表一一对应,可以直接按表补装对应 extra,无需手动搜索包名。
小结与选型建议
| 场景 | 推荐方式 |
|---|---|
| Python 新手 / 需要 NumPy、SciPy、Matplotlib 全家桶 | Anaconda 发行版(注意其 pandas 非官方管理) |
| 使用 conda 的成熟用户 | conda install -c conda-forge pandas,推荐 Miniforge + 虚拟环境 |
| 使用 pip / venv 的用户 | pip install pandas,按需追加 extras,如 pip install "pandas[excel, performance]" |
| 需要最新特性或验证 bug 修复 | nightly wheel:pip install --pre --extra-index-url https://pypi.anaconda.org/scientific-python-nightly-wheels/simple pandas |
| 为 pandas 贡献代码 | 按 贡献指南 与 创建开发环境 从源码构建 |
| 验证安装正确性 | pytest pandas(源码安装)或 pd.test(),测试依赖用 pip install "pandas[test]" |
无论选择哪种方式,都建议在虚拟环境中安装,并按需(而非全量)安装可选依赖:pandas[all] 虽方便,但会引入大量仅在特定场景使用的包;按上表按需安装,既能控制环境体积,又能获得完整的功能支持。