在 Linux 上安装

在大多数情况下，install.packages("arrow") 应该可以直接运行。本文档中记录了一些可以加快安装速度的方法。如果由于某些原因安装不成功，请设置环境变量 ARROW_R_DEV=true，然后重试，并将日志分享给我们。

背景

Apache Arrow 项目是用多种语言实现的，R 软件包依赖于 Arrow C++ 库（从现在开始称为 libarrow）。这意味着当你安装 Arrow 时，你需要 R 和 C++ 版本。如果你在 Windows 或 macOS 机器上从 CRAN 安装 Arrow，当你调用 install.packages("arrow") 时，将下载一个包含 R 软件包和 libarrow 的预编译二进制文件。但是，CRAN 不为 Linux 提供 R 软件包二进制文件，因此你必须从以下替代方法中选择一种。

本文档概述了在 Linux 上安装 Arrow 的推荐方法，从最简单、最不可定制的方法开始，到最复杂但具有更大灵活性来定制安装的方法。

本文档的主要受众是 Linux 上的 Arrow R 软件包“用户”，而不是 Arrow “开发者”。有关开发人员的其他资源列在本文档的末尾。

系统依赖

Arrow 软件包设计为只需非常少的系统要求即可工作，但有几点需要注意。

编译器

从 10.0.0 版本开始，Arrow 需要 C++17 编译器才能构建。对于 gcc，这通常意味着版本 7 或更高版本。大多数现代 Linux 发行版都有足够新的编译器；然而，CentOS 7 是一个明显的例外，因为它附带的是 gcc 4.8。

库

对从云存储（AWS S3 和 Google Cloud Storage (GCS)）读取的可选支持需要额外的系统依赖项

• CURL：安装 libcurl-devel (rpm) 或 libcurl4-openssl-dev (deb)
• OpenSSL >= 1.0.2：安装 openssl-devel (rpm) 或 libssl-dev (deb)

预构建的二进制文件默认启用 S3 和 GCS 支持，因此你需要满足这些系统要求才能使用它们。如果你从源代码构建所有内容，安装脚本将检查这些依赖项是否存在，如果前提条件不满足，则在构建中关闭 S3 和 GCS 支持——安装将成功，但没有 S3 或 GCS 功能。如果之后你安装了缺失的系统要求，则需要重新安装软件包才能启用 S3 和 GCS 支持。

安装发布版本（简易方法）

在 macOS 和 Windows 上，当你运行 install.packages("arrow") 并从 CRAN 安装 Arrow 时，你会得到一个包含 libarrow 预编译版本的 R 二进制软件包。安装二进制文件比从源代码安装容易得多，但 CRAN 不为 Linux 提供二进制文件。这意味着当你在 Linux 上运行 install.packages() 时的默认行为是检索 R 软件包的源代码版本，并从源代码编译 R 软件包和 libarrow。我们将在下一节（“不那么容易”的方法）讨论这种情况，但首先我们将建议两种通常更容易的更快替代方案。

通过 RSPM/conda 安装包含 libarrow 二进制文件的 R 二进制软件包

如果你想要更快的安装过程，并且默认情况下是功能更齐全的构建，你可以从RStudio 的公共软件包管理器安装 Arrow，该管理器为 Windows 和 Linux 提供二进制文件。

例如，如果你使用的是 Ubuntu 20.04 (Focal)

options(
  HTTPUserAgent =
    sprintf(
      "R/%s R (%s)",
      getRversion(),
      paste(getRversion(), R.version["platform"], R.version["arch"], R.version["os"])
    )
)

install.packages("arrow", repos = "https://packagemanager.rstudio.com/all/__linux__/focal/latest")

请注意，User Agent 标头必须按照上面的示例指定。有关更多详细信息，请查看RStudio Package Manager：Admin Guide。

对于其他 Linux 发行版，要获取相关 URL，你可以访问RSPM 站点，点击“binary”，然后选择你喜欢的发行版。

同样，如果你使用 conda 管理你的 R 环境，你可以通过以下方式获取包含 libarrow 的最新官方 R 软件包版本

# Using the --strict-channel-priority flag on `conda install` causes very long
# solve times, so we add it directly to the config
conda config --set channel_priority strict
conda install -c conda-forge r-arrow

包含 libarrow 二进制文件的 R 源代码包

另一种实现更快安装并启用所有关键功能的方法是使用我们托管的静态 libarrow 二进制文件。根据允许列表，这些文件会在许多 Linux 发行版（仅限 x86_64 架构）上自动使用。如果你的发行版不在列表中，你可以在调用 install.packages() 之前设置 NOT_CRAN 环境变量来选择启用。

Sys.setenv("NOT_CRAN" = "true")
install.packages("arrow")

这将安装 R 软件包的源代码版本，但在安装过程中会检查我们托管的兼容 libarrow 二进制文件，如果可用则使用它们。如果没有可用的二进制文件或找不到，则此选项会回退到下面的方法 2（完整源代码构建），但设置环境变量会产生比默认情况功能更齐全的构建。

libarrow 二进制文件包含对 AWS S3 和 GCS 的支持，因此它们需要单独安装 libcurl 和 openssl 库，如上所述。如果你没有安装这些库，将不会使用 libarrow 二进制文件，你将回退到完整的源代码构建（S3 和 GCS 支持将被禁用）。

如果你的计算机的互联网访问不允许下载 libarrow 二进制文件（例如，如果访问仅限于 CRAN），你可以首先通过尝试在离线计算机上安装来确定正确的源和版本

Sys.setenv("NOT_CRAN" = "true", "LIBARROW_BUILD" = FALSE, "ARROW_R_DEV" = TRUE)
install.packages("arrow")
# This will fail if no internet access, but will print the binaries URL

然后你可以获取 libarrow 二进制文件（使用有互联网访问的计算机）并将 zip 文件传输到目标计算机。现在你只需告诉安装程序使用该预下载文件

# Watchout: release numbers of the pre-downloaded libarrow must match CRAN!
Sys.setenv("ARROW_DOWNLOADED_BINARIES" = "/path/to/downloaded/libarrow.zip")
install.packages("arrow")

安装发布版本（不那么容易）

安装 Arrow 的“不那么容易”方法是从源代码安装 R 软件包和底层 Arrow C++ 库 (libarrow)。此方法有些困难，因为编译和安装具有 C++ 依赖项的 R 软件包通常需要安装你可能没有权限执行的系统软件包，和/或单独构建 C++ 依赖项，这会引入各种额外的错误可能性。

从 Arrow 的完整源代码构建安装，编译 C++ 和 R 绑定，将为你处理大部分依赖管理，但这比使用二进制文件慢得多。但是，如果使用二进制文件不是你的选择，或者你希望自定义你的 Linux 安装，本节中的说明将解释如何执行此操作。

基本配置

如果你希望从源代码安装 libarrow 而不是寻找预编译的二进制文件，你可以设置 LIBARROW_BINARY 变量。

Sys.setenv("LIBARROW_BINARY" = FALSE)

默认情况下，这设置为 TRUE，因此只有当此环境变量设置为 FALSE 或找不到与你的操作系统兼容的二进制文件时，才会从源代码构建 libarrow。

从源代码编译 libarrow 时，你可以微调要安装的功能。你可以将环境变量 LIBARROW_MINIMAL 设置为 FALSE 以启用包含 S3 支持和替代内存分配器的功能更齐全的构建。

Sys.setenv("LIBARROW_MINIMAL" = FALSE)

默认情况下，此变量未设置，它会构建许多常用功能，例如 Parquet 支持，但会禁用一些构建成本较高的功能，例如 S3 和 GCS 支持。如果设置为 TRUE，则会安装一个精简版 Arrow，所有可选功能都已禁用。

请注意，在本指南中，你将看到我们提到环境变量 NOT_CRAN - 这是一个方便的变量，当设置为 TRUE 时，它会自动将 LIBARROW_MINIMAL 设置为 FALSE，将 LIBARROW_BINARY 设置为 TRUE。

从源代码构建 libarrow 需要比安装二进制文件更多的时间和资源。我们建议你将环境变量 ARROW_R_DEV 设置为 TRUE，以便在安装过程中出现任何问题时获得更详细的输出。

Sys.setenv("ARROW_R_DEV" = TRUE)

设置完这些变量后，调用 install.packages() 以使用此配置安装 Arrow。

install.packages("arrow")

下面的部分讨论了在调用 install.packages("arrow") 之前可以设置的环境变量，以便从源代码构建并自定义你的配置。

处理 libarrow 依赖项

当你从源代码构建 libarrow 时，其依赖项将自动下载。环境变量 ARROW_DEPENDENCY_SOURCE 控制 libarrow 安装是下载或安装所有依赖项（设置为 BUNDLED 时），仅使用系统安装的依赖项（设置为 SYSTEM 时），还是首先检查系统安装的依赖项，然后仅安装尚不存在的依赖项（设置为 AUTO 时，这是默认值）。

这些依赖项因平台而异；但是，如果你希望在 libarrow 安装之前自行安装这些依赖项，我们建议你查看我们 CI 构建的 docker 文件（以“cpp”结尾的文件用于构建 Arrow 的 C++ 库，即 libarrow），选择与你的设置最接近的文件。这将包含有关依赖项和最低版本的最新信息。

如果在构建时无法下载依赖项，例如在断开连接或防火墙后面的系统上构建时，有几种选择。请参阅下面的“离线构建”。

S3 和 GCS 支持的依赖项

S3 和 GCS 数据处理支持在默认的源代码构建中未启用，并且它有如上所述的额外系统要求。要启用它，请设置环境变量 LIBARROW_MINIMAL=false 或 NOT_CRAN=true 以选择功能齐全的构建，或者更选择性地设置 ARROW_S3=ON 和/或 ARROW_GCS=ON。

当启用任一功能时，安装脚本将检查所需依赖项的存在，如果满足先决条件，它将关闭 S3 和 GCS 支持——安装将成功，但没有 S3 或 GCS 功能。如果之后你安装了缺失的系统要求，则需要重新安装软件包以启用 S3 和 GCS 支持。

高级配置

在本节中，我们将描述如何更精细地微调你的安装。

libarrow 配置

当你从源代码构建 Arrow 时，某些功能是可选的——你可以通过使用环境变量来配置是否构建这些组件。控制这些功能的环境变量名称及其默认值如下所示。

姓名	描述	默认值
ARROW_S3	S3 支持（如果满足依赖项）*	OFF
ARROW_GCS	GCS 支持（如果满足依赖项）*	OFF
ARROW_JEMALLOC	jemalloc 内存分配器	ON
ARROW_MIMALLOC	mimalloc 内存分配器	ON
ARROW_PARQUET		ON
ARROW_DATASET		ON
ARROW_JSON	JSON 解析库	ON
ARROW_WITH_RE2	RE2 正则表达式库，用于某些字符串计算函数	ON
ARROW_WITH_UTF8PROC	UTF8Proc 字符串库，用于许多其他字符串计算函数	ON
ARROW_WITH_BROTLI	压缩算法	ON
ARROW_WITH_BZ2	压缩算法	ON
ARROW_WITH_LZ4	压缩算法	ON
ARROW_WITH_SNAPPY	压缩算法	ON
ARROW_WITH_ZLIB	压缩算法	ON
ARROW_WITH_ZSTD	压缩算法	ON

R 软件包配置

还有许多其他变量会影响 configure 脚本和捆绑的构建脚本。所有布尔变量都不区分大小写。

姓名	描述	默认
LIBARROW_BUILD	允许从源代码构建	true
LIBARROW_BINARY	尝试安装 libarrow 二进制文件而不是从源代码构建	（未设置）
LIBARROW_DOWNLOAD	设置为 false 以明确禁止获取 libarrow 二进制文件	（未设置）
LIBARROW_MINIMAL	构建时启用最小功能	（未设置）
NOT_CRAN	将 LIBARROW_BINARY=true 和 LIBARROW_MINIMAL=false 设置为	false
ARROW_R_DEV	更详细的消息和重新生成一些代码	false
ARROW_USE_PKG_CONFIG	使用 pkg-config 搜索 libarrow 安装	true
LIBARROW_DEBUG_DIR	保存源代码构建日志的目录	（未设置）
CMAKE	替代 CMake 路径	（未设置）

有关这些环境变量的更深入解释，请参见下文。

• LIBARROW_BINARY：默认情况下在许多发行版上，或者如果明确设置为 true，脚本将确定是否存在与你的系统兼容的预构建 libarrow。你可以将其设置为 false 以完全跳过此选项，或者你可以指定一个“distro-version”字符串，对应于可用的二进制文件，以覆盖此函数可能默认发现的内容。可能的值有：“linux-openssl-1.0”、“linux-openssl-1.1”、“linux-openssl-3.0”。
• LIBARROW_BUILD：如果设置为 false，构建脚本将不会尝试从源代码构建 C++。这意味着只有在找到预构建的二进制文件时，你才能获得一个可用的 arrow R 软件包。如果你想避免编译 C++ 库（这可能很慢且占用资源），并确保只使用预构建的二进制文件，请使用此选项。
• LIBARROW_MINIMAL：如果设置为 false，构建脚本将启用一些可选功能，包括 S3 支持和额外的替代内存分配器。这将增加源代码构建时间，但会产生功能更齐全的库。如果设置为 true，则会关闭 Parquet、Datasets、压缩库和其他可选功能。这不常用，但在需要在不支持这些功能的平台上（例如 Solaris）编译时可能会有所帮助。
• NOT_CRAN：如果此变量设置为 true，如 devtools 软件包所做，则构建脚本将设置 LIBARROW_BINARY=true 和 LIBARROW_MINIMAL=false，除非这些环境变量已经设置。这为工作流中已将 NOT_CRAN=true 设置的用户提供了更完整、更快的安装体验，而无需设置额外的环境变量。
• ARROW_R_DEV：如果设置为 true，构建脚本中将打印更详细的消息。arrow::install_arrow(verbose = TRUE) 设置此变量。如果你正在修改软件包中的 C++ 代码，也需要此变量：请参阅开发人员指南文章。
• ARROW_USE_PKG_CONFIG：如果设置为 false，configure 脚本将不会在你的系统上查找 Arrow 库，而是会尝试下载/构建它们。如果你安装的系统库与你安装的 R 软件包版本之间存在版本不匹配，请使用此选项。（后者是 install_arrow() 的默认设置。）系统 libarrow 版本对应于所有 CRAN 发布版本，但不适用于 nightly 或 dev 版本，因此根据你安装的 R 软件包版本，系统 libarrow 版本可能不是一个选项。
• LIBARROW_DEBUG_DIR：如果从源代码构建 C++ 库失败（cmake），可能会有消息告诉你检查构建目录中的某个日志文件。但是，当在 R 软件包安装期间构建库时，该位置在已删除的临时目录中。要捕获这些日志，请将此变量设置为绝对（非相对）路径，日志文件将被复制到该处。如果目录不存在，则会创建该目录。
• CMAKE：从源代码构建 C++ 库时，你可以指定 /path/to/cmake 以使用与 $PATH 上找到的任何版本不同的版本。

使用 install_arrow()

前面的说明对于全新安装 Arrow 很有用，但 Arrow 提供了函数 install_arrow()。此函数有三种常见用例

• 你已安装 Arrow 并想升级到不同版本
• 你想尝试重新安装并修复 Linux C++ 二进制文件的问题
• 你想安装开发版本

使用 install_arrow() 的示例如下所示

install_arrow()               # latest release
install_arrow(nightly = TRUE) # install development version
install_arrow(verbose = TRUE) # verbose output to debug install errors

尽管此函数是 arrow 软件包的一部分，但它也可以作为独立脚本使用，因此你无需先安装软件包即可访问它

source("https://raw.githubusercontent.com/apache/arrow/main/r/R/install-arrow.R")

备注

• install_arrow() 不需要设置环境变量即可满足 C++ 依赖项。
• 与 tensorflow、blogdown 等需要外部依赖项的软件包不同，在成功安装 Arrow 后，你无需运行 install_arrow()。

离线安装

上一节中提到的 install-arrow.R 文件包含一个名为 create_package_with_all_dependencies() 的函数。通常，当在有互联网连接的计算机上安装时，构建过程将根据需要下载第三方依赖项。此函数提供了一种预先下载它们的方法，这在没有互联网连接的计算机上安装 Arrow 时非常有用。过程如下

步骤 1. 使用有互联网连接的计算机，下载依赖项

• 安装 arrow 软件包 或 使用以下命令直接引用脚本

  source("https://raw.githubusercontent.com/apache/arrow/main/r/R/install-arrow.R")

• 使用 create_package_with_all_dependencies() 函数创建安装包

  create_package_with_all_dependencies("my_arrow_pkg.tar.gz")

• 将新创建的 my_arrow_pkg.tar.gz 文件复制到没有互联网连接的计算机

步骤 2. 在没有互联网连接的计算机上，安装准备好的软件包

• 从复制的文件安装 arrow 软件包

  install.packages(
    "my_arrow_pkg.tar.gz",
    dependencies = c("Depends", "Imports", "LinkingTo")
   )

  此安装将从源代码构建，因此必须提供 cmake

• 运行 arrow_info() 检查已安装的功能

备注

• 在没有互联网连接的计算机上，即使不使用此函数，也可以安装 Arrow，但许多有用的功能将被禁用，因为它们依赖于第三方组件。更确切地说，arrow::arrow_info()$capabilities() 对于所有功能都将为 FALSE。

• 如果你正在使用二进制软件包，则不需要此函数。你可以从你的软件包存储库下载相应的二进制文件，将其传输到离线计算机，然后安装它。

• 如果你在 Linux 上使用 RStudio Package Manager (RSPM)，并且想使用此函数创建源代码包，请确保将 options("repos") 中的第一个存储库设置为包含源代码包的镜像。也就是说，该存储库需要是 RSPM 二进制镜像 URL 以外的其他内容。

离线安装（备选方案）

离线安装的第二种方法需要更多的手动操作。如果你想尝试，请按照以下步骤操作

• 下载依赖文件（cpp/thirdparty/download_dependencies.sh 可能会有帮助）
• 将依赖项目录复制到离线计算机
• 在离线计算机上创建环境变量 ARROW_THIRDPARTY_DEPENDENCY_DIR，指向复制的目录。
• 像往常一样安装 arrow 软件包。

有关使用 libarrow 二进制文件进行离线安装，请参阅上面的方法 1b。

故障排除

目的是 install.packages("arrow") 能够正常工作并处理所有 C++ 依赖项，但根据你的系统，如果你调整几个参数之一，可能会获得更好的结果。以下是一些已知的问题和解决方法。

软件包未能构建 C++ 依赖项

如果软件包安装失败时，在输出中看到类似以下消息

------------------------- NOTE ---------------------------
There was an issue preparing the Arrow C++ libraries.
See https://arrow.apache.org/docs/r/articles/install.html
---------------------------------------------------------

这意味着安装未能检索或构建与当前 R 软件包版本兼容的 libarrow 版本。

请查看下面的“已知安装问题”以查看是否有任何适用，如果没有适用，请设置环境变量 ARROW_R_DEV=TRUE 以获取更详细的输出并尝试再次安装。然后，请报告问题并附上完整的安装输出。

使用系统库

如果找到系统库或已安装的 Arrow，但它与 R 软件包版本不匹配（例如，你的系统上有 libarrow 1.0.0，而你正在安装 R 软件包 2.0.0），则 R 绑定很可能无法编译。由于 Apache Arrow 项目正在积极开发中，libarrow 和 R 软件包的版本匹配至关重要。当 install.packages("arrow") 必须下载 libarrow 时，安装脚本会确保你获取与你的 R 软件包版本对应的 libarrow 版本。但是，如果你正在使用系统上已有的 libarrow 版本，则无法保证版本匹配。

要解决版本不匹配问题，你可以更新你的 libarrow 系统软件包以匹配 R 软件包版本，或者设置环境变量 ARROW_USE_PKG_CONFIG=FALSE，告诉配置脚本不要查找 libarrow 的系统版本。（后者是 install_arrow() 的默认设置。）系统 libarrow 版本对应于所有 CRAN 发布版本，但不支持 nightly 或开发版本，因此根据你安装的 R 软件包版本，系统 libarrow 版本可能不是一个选项。

另请注意，一旦你基于系统（共享）库成功安装了 R 软件包，如果你更新了系统 libarrow 安装，则需要重新安装 R 软件包以匹配其版本。同样，如果你正在使用 libarrow 系统库，那么在 arrow 软件包发布新版本后运行 update.packages() 可能会失败，除非你首先更新 libarrow 系统软件包。

使用预构建二进制文件

如果 R 软件包找到了并下载了 libarrow 的预构建二进制文件，但之后 Arrow 软件包无法加载，可能出现“未定义符号”错误，请报告问题。这很可能是编译器不匹配，可以通过设置一些环境变量来解决，以指示 R 编译软件包以匹配 libarrow。

一个解决方法是设置环境变量 LIBARROW_BINARY=FALSE 并重新尝试安装：此值指示软件包从源代码构建 libarrow，而不是下载预构建的二进制文件。这应该能保证编译器设置匹配。

如果你的操作系统没有找到预构建的 libarrow 二进制文件，但你认为应该有，请报告问题并分享控制台输出。你还可以设置环境变量 ARROW_R_DEV=TRUE 以获取额外的调试消息。

从源代码构建 libarrow

如果从源代码构建 libarrow 失败，请检查错误消息。（如果你没有看到错误消息，只有 ----- NOTE -----，请设置环境变量 ARROW_R_DEV=TRUE 以增加详细程度并重新尝试安装。）安装脚本应该在任何地方都可以工作，因此如果 libarrow 编译失败，请报告问题，以便我们改进脚本。

贡献

我们不断努力使安装过程尽可能地轻松。如果你发现改进过程的方法，请报告问题，以便我们记录下来。同样，如果你发现你的 Linux 发行版或版本不受支持，我们欢迎贡献 Docker 镜像（托管在 Docker Hub 上），我们可以将其用于持续集成，并希望提高我们的覆盖率。如果你确实贡献了一个 Docker 镜像，它应该尽可能精简，只包含 R 及其所需的依赖项。作为参考，请参阅 R-hub 使用的镜像。

你可以使用 apache/arrow git 仓库中包含的 docker compose 设置来测试 arrow R 软件包安装。例如，

R_ORG=rhub R_IMAGE=ubuntu-release R_TAG=latest docker compose build r
R_ORG=rhub R_IMAGE=ubuntu-release R_TAG=latest docker compose run r

在 rhub/ubuntu-release 镜像上安装 arrow R 软件包，包括 libarrow。

进一步阅读

• 要了解如何安装开发版本，请参阅关于安装夜间构建的文章。
• 如果你正在为 Arrow 项目做贡献，请参阅Arrow R 开发人员指南，获取帮助你设置开发环境的资源。
• Arrow 开发人员可能还希望阅读安装详情文章中描述的安装过程中运行的代码的更详细讨论。