构建 PyArrow#

本页面提供所有平台 PyArrow 的源构建说明。

系统要求#

在 macOS 上，任何现代 Xcode 或 Xcode 命令行工具（xcode-select --install）都足够了。

在 Linux 上，对于本指南，我们要求最低版本为 gcc 或 clang 9。您可以通过运行以下命令检查您的版本：

$ gcc --version

如果系统编译器版本低于 gcc 9，可以使用 $CC 和 $CXX 环境变量将其设置为较新版本

$ export CC=gcc-9
$ export CXX=g++-9

在 Windows 上构建需要安装以下编译器之一

在构建工具设置过程中，请确保至少选择一个 Windows SDK。

环境设置#

首先，从全新的 Apache Arrow 克隆开始

$ git clone https://github.com/apache/arrow.git

有两种受支持的方式来设置 PyArrow 的构建环境：使用 Conda 管理依赖项或使用 pip 进行手动依赖项管理。

以下将针对 Linux 和 macOS 演示这两种方法。对于 Windows，目前只记录了基于 Conda 的设置，并跳过了一些仅限 Linux/macOS 的软件包。

请注意，如果您不在 Windows 平台上使用 conda，则需要将 Arrow C++ 库与 pyarrow 捆绑在一起。有关更多信息，请参阅 构建 PyArrow 部分下的 Windows 选项卡。

拉取测试数据并设置环境变量

$ pushd arrow
$ git submodule update --init
$ export PARQUET_TEST_DATA="${PWD}/cpp/submodules/parquet-testing/data"
$ export ARROW_TEST_DATA="${PWD}/testing/data"
$ popd

conda 包管理器允许将 Arrow C++ 和 PyArrow 的构建时依赖项作为预构建二进制文件安装，这可以使 Arrow 开发更轻松、更快。

让我们创建一个 conda 环境，其中包含来自 conda-forge 的所有 C++ 构建和 Python 依赖项，目标是 Python 3.13 的开发

$ conda create -y -n pyarrow-dev -c conda-forge \
      --file arrow/ci/conda_env_unix.txt \
      --file arrow/ci/conda_env_cpp.txt \
      --file arrow/ci/conda_env_python.txt \
      --file arrow/ci/conda_env_gandiva.txt \
      compilers \
      python=3.13 \
      pandas

截至 2019 年 1 月，许多 Linux 发行版都需要 compilers 包才能使用 conda-forge 的包。

完成此操作后，您现在可以激活 conda 环境

$ conda activate pyarrow-dev

我们需要设置一些环境变量，以便让 Arrow 的构建系统了解我们的构建工具链

$ export ARROW_HOME=$CONDA_PREFIX

警告

如果您使用 Anaconda 分发版或 Miniconda 安装了 Python，您目前无法使用基于 pip 的虚拟环境。请改为遵循基于 conda 的开发说明。

拉取测试数据并设置环境变量

$ pushd arrow
$ git submodule update --init
$ export PARQUET_TEST_DATA="${PWD}/cpp/submodules/parquet-testing/data"
$ export ARROW_TEST_DATA="${PWD}/testing/data"
$ popd

使用系统和捆绑依赖项

如果不使用 conda，您必须安排您的系统提供所需的构建工具和依赖项。请注意，如果缺少某些依赖项，Arrow C++ 构建链可能仍然能够动态下载和编译它们，但这将比使用预安装的二进制文件花费更长的时间。

在 macOS 上，使用 Homebrew 安装构建 Arrow C++ 所需的所有依赖项

$ brew update && brew bundle --file=arrow/cpp/Brewfile

有关您可能需要的依赖项列表，请参阅此处。

在 Debian/Ubuntu 上，您需要以下最少依赖项集

$ sudo apt-get install build-essential ninja-build cmake python3-dev

现在，让我们创建一个 Python 虚拟环境，其中包含与存储库在同一文件夹中的所有 Python 依赖项，以及一个目标安装文件夹

$ python3 -m venv pyarrow-dev
$ source ./pyarrow-dev/bin/activate
$ pip install -r arrow/python/requirements-build.txt

$ # This is the folder where we will install the Arrow libraries during
$ # development
$ mkdir dist

如果您的 Linux 上的 CMake 版本太旧，可以通过 pip install cmake 获取更新的版本。

我们需要设置一些环境变量，以便让 Arrow 的构建系统了解我们的构建工具链

$ export ARROW_HOME=$(pwd)/dist
$ export LD_LIBRARY_PATH=$(pwd)/dist/lib:$LD_LIBRARY_PATH
$ export CMAKE_PREFIX_PATH=$ARROW_HOME:$CMAKE_PREFIX_PATH

让我们创建一个 conda 环境，其中包含来自 conda-forge 的所有 C++ 构建和 Python 依赖项，目标是 Python 3.13 的开发

$ conda create -y -n pyarrow-dev -c conda-forge ^
      --file arrow\ci\conda_env_cpp.txt ^
      --file arrow\ci\conda_env_python.txt ^
      --file arrow\ci\conda_env_gandiva.txt ^
      python=3.13
$ conda activate pyarrow-dev

现在，我们可以构建和安装 Arrow C++ 库。

我们将 Arrow C++ 库的安装目录路径设置为 ARROW_HOME。使用 conda 环境时，Arrow C++ 安装在环境目录中，其路径保存在 CONDA_PREFIX 环境变量中。

$ set ARROW_HOME=%CONDA_PREFIX%\Library

构建#

首先我们需要配置、构建和安装 Arrow C++ 库。然后我们可以构建 PyArrow。

构建 C++#

现在构建 Arrow C++ 库并将它们安装到我们上面创建的目录（存储在 $ARROW_HOME 中）

$ cmake -S arrow/cpp -B arrow/cpp/build \
      -DCMAKE_INSTALL_PREFIX=$ARROW_HOME \
      --preset ninja-release-python
$ cmake --build arrow/cpp/build --target install

关于预设

ninja-release-python 并不是唯一可用的预设——如果您想要一个具有更多功能（如 CUDA、Flight 和 Gandiva 支持）的构建，您可以选择 ninja-release-python-maximal 预设。如果您想要较少的功能（即删除 ORC 和数据集支持），您可以选择 ninja-release-python-minimal。将上述任何预设中的 release 更改为 debug 将生成 Arrow 的调试构建。

单独的组件

提供预设是为了方便，但您也可以选择指定单独的组件

$ cmake -S arrow/cpp -B arrow/cpp/build \
      -DCMAKE_INSTALL_PREFIX=$ARROW_HOME \
      -DCMAKE_BUILD_TYPE=Debug \
      -DARROW_BUILD_TESTS=ON \
      -DARROW_COMPUTE=ON \
      -DARROW_CSV=ON \
      -DARROW_DATASET=ON \
      -DARROW_FILESYSTEM=ON \
      -DARROW_HDFS=ON \
      -DARROW_JSON=ON \
      -DARROW_PARQUET=ON \
      -DARROW_WITH_BROTLI=ON \
      -DARROW_WITH_BZ2=ON \
      -DARROW_WITH_LZ4=ON \
      -DARROW_WITH_SNAPPY=ON \
      -DARROW_WITH_ZLIB=ON \
      -DARROW_WITH_ZSTD=ON \
      -DPARQUET_REQUIRE_ENCRYPTION=ON
$ cmake --build arrow/cpp/build --target install -j4

如果您的环境中安装了多个 Python 版本，您可能需要向 CMake 传递额外的参数，以便它可以找到正确的执行文件、头文件和库。例如，指定 -DPython3_EXECUTABLE=<path/to/bin/python> 让 CMake 选择您正在使用的 Python 可执行文件。

注意

在支持多架构构建的 Linux 系统上，make 可能会默认将库安装在 lib64 目录中。因此，我们建议传递 -DCMAKE_INSTALL_LIBDIR=lib，因为 Python 构建脚本假定库目录是 lib

注意

如果您安装了 conda 但未使用它来管理依赖项，并且在构建 C++ 库时遇到问题，您可能需要设置 -DARROW_DEPENDENCY_SOURCE=AUTO 或其他值（此处描述），以明确告诉 CMake 不要使用 conda。

为方便起见，提供了用于构建 C++ 的预设（参见 Linux 和 macOS 选项卡）。这里我们将改为指定单个组件

$ mkdir arrow\cpp\build
$ pushd arrow\cpp\build
$ cmake -G "Ninja" ^
      -DCMAKE_INSTALL_PREFIX=%ARROW_HOME% ^
      -DCMAKE_UNITY_BUILD=ON ^
      -DARROW_COMPUTE=ON ^
      -DARROW_CSV=ON ^
      -DARROW_CXXFLAGS="/WX /MP" ^
      -DARROW_DATASET=ON ^
      -DARROW_FILESYSTEM=ON ^
      -DARROW_HDFS=ON ^
      -DARROW_JSON=ON ^
      -DARROW_PARQUET=ON ^
      -DARROW_WITH_LZ4=ON ^
      -DARROW_WITH_SNAPPY=ON ^
      -DARROW_WITH_ZLIB=ON ^
      -DARROW_WITH_ZSTD=ON ^
      ..
$ cmake --build . --target install --config Release
$ popd

可选构建组件#

有几个可选组件可以通过将特定标志分别设置为 ON 或 OFF 来启用或禁用。请参阅下面的相关组件和环境变量列表。

您可以选择不同类型的 C++ 构建类型

  • -DCMAKE_BUILD_TYPE=Release（默认值）生成启用优化且禁用调试信息的构建；

  • -DCMAKE_BUILD_TYPE=Debug 生成禁用优化且启用调试信息的构建；

  • -DCMAKE_BUILD_TYPE=RelWithDebInfo 生成启用优化和调试信息的构建。

另请参阅

构建 Arrow C++.

有关任何其他 C++ 构建挑战，请参阅 C++ 开发。

如果由于过程中的错误需要重新构建 C++ 部分，建议删除构建文件夹，请参阅 相关组件和环境变量。如果构建已成功通过并且由于从 git main 的最新拉取而需要重新构建，则无需此步骤。

构建 PyArrow#

如果您在 C++ 中构建了可选组件之一，那么 PyArrow 的构建将默认启用等效组件。此默认值可以通过将相应的 PYARROW_WITH_$COMPONENT 环境变量设置为 0 或 1 来覆盖，请参阅下面的相关组件和环境变量。

要构建 PyArrow，请运行

$ pushd arrow/python
$ python setup.py build_ext --inplace
$ popd

$ pushd arrow\python
$ python setup.py build_ext --inplace
$ popd

注意

如果您将 Conda 与 Python 3.9 或更早版本一起使用，则必须设置 CONDA_DLL_SEARCH_MODIFICATION_ENABLE=1。

注意

根据上述说明，Arrow C++ 库不与 Python 扩展捆绑。这建议用于开发，因为它允许单独重新构建 C++ 库。

如果您正在使用 conda 包管理器，那么 conda 将确保找到 Arrow C++ 库。如果您没有使用 conda，那么您必须

  • 每次导入 pyarrow 之前将已安装的 DLL 库路径添加到 PATH，或者

  • 将 Arrow C++ 库与 pyarrow 捆绑。

捆绑 Arrow C++ 和 PyArrow

如果您想将 Arrow C++ 库与 pyarrow 捆绑，请在构建 pyarrow 之前设置 PYARROW_BUNDLE_ARROW_CPP 环境变量

$ set PYARROW_BUNDLE_ARROW_CPP=1
$ python setup.py build_ext --inplace

请注意，重新构建 Arrow C++ 时，捆绑的 Arrow C++ 库不会自动更新。

要设置用于编译 PyArrow C++/Cython 组件的线程数，请设置 PYARROW_PARALLEL 环境变量。

如果您构建 PyArrow 后又修改了 Arrow C++ 或 PyArrow 代码，可能会导致构建产物过时。这可能导致意外行为或错误。为避免这种情况，您可以在重新构建之前清理构建产物。请参阅相关组件和环境变量。

默认情况下，即使 Arrow C++ 以调试模式构建，PyArrow 也会以发布模式构建。要创建 PyArrow 的调试构建，请在运行上述 python setup.py build_ext --inplace 之前运行 export PYARROW_BUILD_TYPE=debug。可以类似地创建 relwithdebinfo 构建。

自包含轮子#

如果您正在准备用于分发（例如，用于 PyPI）的 PyArrow 轮子，您需要构建一个自包含的轮子（包括 Arrow 和 Parquet C++ 库）。这确保了所有必要的本机库都捆绑在轮子中，因此用户无需在其系统上单独安装 Arrow 或 Parquet 即可安装它。

为此，请将 --bundle-arrow-cpp 选项传递给构建命令

$ pip install wheel  # if not installed
$ python setup.py build_ext --build-type=$ARROW_BUILD_TYPE \
         --bundle-arrow-cpp bdist_wheel

此选项通常仅用于发布或分发场景，不用于本地开发。

可编辑安装#

要安装可编辑的 PyArrow 构建，请从 arrow/python 目录运行以下命令

pip install -e . --no-build-isolation``

这会创建一个可编辑安装，这意味着对 Python 源代码的更改会立即反映出来，而无需重新安装包。--no-build-isolation 标志确保构建使用当前环境的依赖项，而不是创建隔离环境。这在开发和调试期间特别有用。

删除过时的构建产物#

当 Arrow C++ 库或 PyArrow 的结构发生变化时，建议进行彻底清理，作为修复构建错误的第一步。

注意

从错误本身不一定直观地看出问题是由于过时的产物造成的。一个由于过时的产物导致的构建错误示例是 Unknown CMake command "arrow_keep_backward_compatibility"。

要删除过时的 Arrow C++ 构建产物

$ rm -rf arrow/cpp/build

要删除过时的 PyArrow 构建产物

$ git clean -Xfd python

如果使用 Conda 环境，则一些构建产物会安装在 $ARROW_HOME（又名 $CONDA_PREFIX）中。例如，$ARROW_HOME/lib/cmake/Arrow*、$ARROW_HOME/include/arrow、$ARROW_HOME/lib/libarrow* 等。

这些文件可以手动删除。如果不确定要擦除哪些文件，一种方法是重新创建 Conda 环境。

要么删除当前的，然后重新开始

$ conda deactivate
$ conda remove -n pyarrow-dev

或者，破坏性较小地，创建一个不同名称的不同环境。

Docker 示例#

如果您在从源代码构建 Python 库时遇到困难，请查看 python/examples/minimal_build 目录，其中演示了使用 conda 和 pip 构建方法的完整源代码构建和测试。

测试#

现在您已准备好安装测试依赖项并运行单元测试，如开发部分所述。

相关组件和环境变量#

可用于构建 PyArrow 的相关环境变量列表为

PyArrow 环境变量

描述

默认值

PYARROW_BUILD_TYPE

PyArrow 的构建类型（release、debug 或 relwithdebinfo），设置 CMAKE_BUILD_TYPE

release

PYARROW_CMAKE_GENERATOR

示例：'Visual Studio 17 2022 Win64'

''

PYARROW_CMAKE_OPTIONS

额外的 CMake 和 Arrow 选项（例如 "-DARROW_SIMD_LEVEL=NONE -DCMAKE_OSX_ARCHITECTURES=x86_64;arm64"）

''

PYARROW_CXXFLAGS

额外的 C++ 编译器标志

''

PYARROW_GENERATE_COVERAGE

将 Cython 编译器的 Xlinetrace 标志设置为 true

false

PYARROW_BUNDLE_ARROW_CPP

捆绑 Arrow C++ 库

0 (OFF)

PYARROW_BUNDLE_CYTHON_CPP

捆绑 Cython 生成的 C++ 文件

0 (OFF)

PYARROW_BUILD_VERBOSE

启用 Makefile 构建的详细输出

0 (OFF)

PYARROW_PARALLEL

用于编译 PyArrow C++/Cython 组件的进程数

''

构建 PyArrow 时禁用或启用的组件默认基于 Arrow C++ 的构建方式（即它遵循 ARROW_$COMPONENT 标志）。但是，PYARROW_WITH_$COMPONENT 环境变量仍然可以在构建 PyArrow 时用于覆盖此设置（例如，禁用组件，或强制构建某些组件）

Arrow 标志/选项

PyArrow 对应的环境变量

ARROW_GCS

PYARROW_WITH_GCS

ARROW_S3

PYARROW_WITH_S3

ARROW_AZURE

PYARROW_WITH_AZURE

ARROW_HDFS

PYARROW_WITH_HDFS

ARROW_CUDA

PYARROW_WITH_CUDA

ARROW_SUBSTRAIT

PYARROW_WITH_SUBSTRAIT

ARROW_FLIGHT

PYARROW_WITH_FLIGHT

ARROW_ACERO

PYARROW_WITH_ACERO

ARROW_DATASET

PYARROW_WITH_DATASET

ARROW_PARQUET

PYARROW_WITH_PARQUET

PARQUET_REQUIRE_ENCRYPTION

PYARROW_WITH_PARQUET_ENCRYPTION

ARROW_ORC

PYARROW_WITH_ORC

ARROW_GANDIVA

PYARROW_WITH_GANDIVA

安装夜间构建包#

警告

这些包并非官方发布。请自行承担使用风险。

PyArrow 在 scientific-python-nightly-wheels 上托管了用于测试目的的夜间构建轮子。

这些可能适用于下游库在其持续集成设置中，以保持与即将推出的 PyArrow 功能、弃用和/或功能移除的兼容性。

要安装最新夜间版本的 PyArrow，请运行

pip install \
  -i https://pypi.anaconda.org/scientific-python-nightly-wheels/simple \
  pyarrow