pandas 安装完全指南:conda-forge、pip、源码构建与依赖体系详解

原创2026-09-18 09:21:511,822 阅读
文章标签:数据分析数据科学数据清洗数据可视化数据集成DataFrame

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 的渠道有三个:

  1. conda-forge:配合 conda 包管理器安装,命令为 conda install -c conda-forge pandas;
  2. PyPI:配合 pip 包管理器安装,命令为 pip install pandas;
  3. 源码分发:从 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 的时区库

版本约束的统一维护

值得注意的是,本文档中所有依赖的最低版本号并非"文档独有",而是与源码中的单一事实来源同步维护的。仓库里存在三处需要保持一致的地方:

  1. pyproject.toml 的 dependencies 与 [project.optional-dependencies]——pip 安装时的硬约束;
  2. pandas/compat/_optional.py 的 VERSIONS 字典——运行时 import_optional_dependency() 校验的版本底线(如 "python-calamine": "0.4.0"、"tables": "3.10.2"),其 INSTALL_MAPPING 还负责导入名到发行包名的翻译;
  3. 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] 虽方便,但会引入大量仅在特定场景使用的包;按上表按需安装,既能控制环境体积,又能获得完整的功能支持。

登录后查看全文
pandas