PyArrow 安装指南详解：从 PyPI/Conda 安装到 conda-forge 三件套包的深度解析

PyArrow 安装指南详解：从 PyPI/Conda 安装到 conda-forge 三件套包的深度解析

【免费下载链接】arrowApache Arrow is the universal columnar format and multi-language toolbox for fast data interchange and in-memory analytics项目地址: https://gitcode.com/GitHub_Trending/arrow3/arrow

本文基于 Apache Arrow 官方文档 install.rst 展开，系统讲解 PyArrow 的官方安装方式、系统/Python 版本兼容范围、可选依赖与 Windows 时区数据库配置要点，并结合 python/CMakeLists.txt、python/pyproject.toml 等仓库源码，深入解析 conda-forge 上pyarrow-core、pyarrow、pyarrow-all三个包的功能划分及其与底层 Arrow C++ 组件的对应关系。读完后你可以：选择正确的安装渠道、理解三个 conda 包的取舍逻辑、按需在 Conda 环境中自定义组件组合，并正确处理 Windows 时区相关的边界问题。

一、系统兼容性与 Python 版本支持

官方文档明确说明：PyArrow 在 Windows、macOS 和各种 Linux 发行版上被定期构建和测试，并强烈建议使用 64 位系统。

关于 Python 版本，文档当前表述为：

PyArrow 目前兼容 Python 3.11、3.12、3.13 和 3.14。

从源码可以进一步印证这一版本边界。python/pyproject.toml 中声明了硬性下限：

requires-python = ">=3.11"

同时classifiers中列出了 3.11 至 3.15 以及 Free Threading（无 GIL 实验性支持）标记（python/pyproject.toml）：

classifiers = [ 'Programming Language :: Python :: 3.11', 'Programming Language :: Python :: 3.12', 'Programming Language :: Python :: 3.13', 'Programming Language :: Python :: 3.14', 'Programming Language :: Python :: 3.15', 'Programming Language :: Python :: Free Threading :: 2 - Beta', ]

可以推断：当前开发主线已将支持下限固定在 3.11，3.15 及 free-threading 构建属于较新的开发目标，实际可用版本请以发布渠道中的 wheel 为准。

二、使用 Conda 安装（推荐方式）

官方推荐大多数用户通过 conda-forge 安装最新版 PyArrow：

conda install -c conda-forge pyarrow

文档中特别提示：pyarrow这个 conda-forge 包对多数用户是正确选择，但同时存在最小变体（pyarrow-core）和完整变体（pyarrow-all），二者可能更适合特定场景。三者的详细差异见下文"conda-forge 三包差异"一节。

三、使用 Pip 安装

从 PyPI 安装最新版（支持 Windows、Linux、macOS）：

pip install pyarrow

文档列出两个平台相关的注意事项，都是实际部署中高频踩坑点：

1. Windows 导入问题：若在 Windows 上使用 pip 安装的 wheel 时遇到导入错误，可能还需要安装最新的 Visual C++ Redistributable for Visual Studio（微软官方提供，文档附有链接指引）。
2. Linux 上的 pip 版本要求：在 Linux 上需要pip >= 19.0才能正确检测到预编译的二进制包（manylinux wheel）。旧版 pip 会回退到源码构建，缺少 Arrow C++ 依赖时会失败。

关于 PyPI 上的构建体系，python/pyproject.toml 显示当前 sdist 的构建后端为scikit-build-core，并要求：

requires = [ "scikit-build-core >= 1.0", "cython >= 3.1", "numpy>=2.0", "setuptools_scm[toml]>=8", ] build-backend = "scikit_build_core.build"

这说明从源码构建 PyArrow 需要完整的 C++ 编译工具链与 Cython ≥ 3.1；对于只想"装来用"的用户，pip 预编译 wheel 是更稳妥的路径。夜间构建包（nightly）与完全从源码安装的步骤，文档指向 Python 开发文档（python-development章节），本文不展开。

四、可选依赖与运行时配套包

官方文档列出的可选依赖：

此外，PyArrow 与以下包兼容：fsspec（文件系统抽象）、以及用于时区的pytz、dateutil或tzdata包。

从仓库的测试依赖清单 python/requirements-test.txt 可以看到上游实际验证过的配套版本组合：

cffi hypothesis packaging pandas; python_version < "3.15" pandas>=3.1.0.dev0; python_version >= "3.15" pytest pytest-xdist pytz

这印证了文档中 pandas 的版本约束（低版本 Python 用稳定版 pandas，Python 3.15 开发线改用 pandas 3.1 开发版），并额外引入了hypothesis、pytest-xdist等测试框架依赖。

4.1 Windows 上的 tzdata 处理

文档中关于时区数据库的说明值得逐条掌握：

• Linux 与 macOS：Arrow 直接使用操作系统提供的时区数据库，无需额外配置。
• Windows + MSVC，或较新 MinGW GCC（13 及以上）：使用 Windows 时区数据库，覆盖大多数预编译包，无需额外设置。
• Windows + Clang/libc++ 构建：需要用户自行提供 IANA 时区数据库。文档给出两条路径：
  • 按 C++ 文档中的"下载时区数据库"步骤操作（见 ci/scripts/download_tz_database.sh 对应的 C++ 侧说明）；
  • 或使用已弃用的工具函数pyarrow.util.download_tzdata_on_windows()。

源码层面，python/pyarrow/util.py 中该函数已明确标注弃用：

def download_tzdata_on_windows(): r""" Download and extract latest IANA timezone database into the location expected by Arrow which is %USERPROFILE%\Downloads\tzdata. .. deprecated:: 24.0.0 This function is deprecated and will be removed in a future version. PyArrow now uses the operating system's timezone database on Windows. """

函数默认将 IANA 时区数据库解压到%USERPROFILE%\Downloads\tzdata；若数据库放在其他位置，需通过（已弃用的）pa.set_timezone_db_path("custom_path")设置自定义路径。python/pyarrow/config.pxi 中可以看到该函数自 24.0.0 起发出FutureWarning，底层通过CGlobalOptions.timezone_db_path在Initialize时注入。对应的行为测试分别在 python/pyarrow/tests/test_util.py（非 Windows 平台调用该函数应抛错）和 python/pyarrow/tests/test_misc.py（非 Windows 平台调用set_timezone_db_path应报错）中验证。

pip 安装写 ORC 文件时的已知问题与解决办法（文档原文 note）：

1. 安装pip install tzdata；
2. 设置环境变量TZDIR = path\to\.venv\Lib\site-packages\tzdata\。

可以用以下命令定位tzdata的安装位置：

import tzdata print(tzdata.__file__) # path\to\.venv\Lib\site-packages\tzdata\__init__.py

五、conda-forge 三包差异：pyarrow-core / pyarrow / pyarrow-all

这是本文的核心技术点。文档指出：在 conda-forge 上，PyArrow 被拆分为三个独立包，功能层级不同；而 PyPI 只发布单一的pyarrow包。拆分的目的是：

• 让多数用户安装最小体积的pyarrow；
• 为特殊场景提供极简的pyarrow-core；
• 为需要完整功能的用户保留pyarrow-all（即历史上 conda-forge 的pyarrow包）。

5.1 各包包含的功能

pyarrow-core包含：

• 数据核心（data）
• 计算库（pyarrow.compute）
• IO（io）
• IPC（pyarrow.ipc）
• 文件系统（pyarrow.fs）。文档注明：云文件系统（S3、GCS 等）计划在未来版本移入pyarrow，但本地文件系统将保留在pyarrow-core中
• 文件格式：Arrow/Feather、JSON、CSV、ORC（不含 Parquet）

pyarrow在此基础上追加：

• Acero（pyarrow.acero）
• Dataset（pyarrow.dataset）
• Parquet（pyarrow.parquet）
• Substrait（pyarrow.substrait）

pyarrow-all再追加：

• Flight 与 Flight SQL（pyarrow.flight）
• Gandiva（pyarrow.gandiva）

5.2 功能-包对应总表

5.3 与源码中 CMake 开关的对应关系

上表并非纸面约定，而是直接映射到构建系统的组件开关。python/CMakeLists.txt 中通过define_option将 PyArrow 各集成模块与 Arrow C++ 的同名开关绑定：

define_option(ACERO "Build the PyArrow Acero integration" ARROW_ACERO) define_option(CUDA "Build the PyArrow CUDA support" ARROW_CUDA) define_option(DATASET "Build the PyArrow Dataset integration" ARROW_DATASET) define_option(FLIGHT "Build the PyArrow Flight integration" ARROW_FLIGHT) define_option(GANDIVA "Build the PyArrow Gandiva integration" ARROW_GANDIVA) define_option(ORC "Build the PyArrow ORC integration" ARROW_ORC) define_option(PARQUET "Build the PyArrow Parquet integration" ARROW_PARQUET) define_option(SUBSTRAIT "Build the PyArrow Substrait integration" ARROW_SUBSTRAIT) define_option(AZURE "Build the PyArrow Azure integration" ARROW_AZURE) define_option(GCS "Build the PyArrow GCS integration" ARROW_GCS) define_option(S3 "Build the PyArrow S3 integration" ARROW_S3) define_option(HDFS "Build the PyArrow HDFS integration" ARROW_HDFS)

从源码结构看，各模块还存在编译期依赖强制：例如启用 Substrait 会连带开启 Dataset，启用 Dataset 会连带开启 Acero（python/CMakeLists.txt）：

# enforce module dependencies if(PYARROW_BUILD_SUBSTRAIT) set(PYARROW_BUILD_DATASET ON) endif() if(PYARROW_BUILD_DATASET) set(PYARROW_BUILD_ACERO ON) endif()

这与文档表格中"pyarrow 包包含 Acero + Dataset + Parquet + Substrait"的组合逻辑一致——Dataset 依赖 Acero 查询执行引擎，因此二者总是一起出现。当对应 Arrow C++ 库缺失时，CMake 会直接报错，如if(NOT ARROW_DATASET) message(FATAL_ERROR "You must build Arrow C++ with ARROW_DATASET=ON")（python/CMakeLists.txt）。

六、创建自定义组件组合

文档"Creating A Custom Selection"小节给出的实操建议：如果你明确知道自己需要哪些组件，可以只安装pyarrow-core并叠加所需功能包，从而精确控制安装体积。

示例 1：core + Parquet——安装pyarrow-core并叠加libparquet：

conda install -c conda-forge pyarrow-core libparquet

示例 2：标准 pyarrow + Flight RPC：

conda install -c conda-forge pyarrow libarrow-flight

由此可以总结一条通用的自定义公式：

pyarrow-core + 按需叠加 { libparquet, libarrow-dataset, libarrow-acero, libarrow-substrait, libarrow-flight, libarrow-flight-sql, libarrow-gandiva }

由于 Dataset/Acero/Substrait 之间的依赖关系（见上一节 CMake 强制逻辑），选择libarrow-dataset时 Acero 会作为其依赖被自动带上，实际安装体积以 conda 求解结果为准。

七、安装方式选择速查

八、小结

PyArrow 的安装体系可以用一句话概括：PyPI 给"开箱即用"，conda-forge 给"精确组合"。官方文档给出的兼容范围（Python ≥ 3.11、64 位系统优先）、三个 conda 包的功能分层表，以及 Windows 时区数据库的分场景处理方式，构成了日常使用与部署的主要决策依据；而 python/CMakeLists.txt 中的组件开关与依赖强制规则，则解释了这些功能分层在构建系统上的真实来源。对于需要控制依赖体积的生产环境，建议按"pyarrow-core + 按需功能库"的方式裁剪；对于需要 Flight RPC 或 Gandiva 的场景，则选择pyarrow-all或叠加libarrow-flight等对应组件。

【免费下载链接】arrowApache Arrow is the universal columnar format and multi-language toolbox for fast data interchange and in-memory analytics项目地址: https://gitcode.com/GitHub_Trending/arrow3/arrow