在 Linux 上安装 • Arrow R 包

在大多数情况下，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 时，您会获得一个 R 二进制包，其中包含 libarrow 的预编译版本。安装二进制文件比从源代码安装容易得多，但 CRAN 不托管 Linux 的二进制文件。这意味着当您在 Linux 上运行 install.packages() 时，默认行为是检索 R 包的源版本并从源代码编译 R 包和 libarrow。我们将在下一节（“不太容易”的方法）中讨论这种情况，但首先我们将提出两个通常容易得多的更快的替代方法。

通过 RSPM/conda 获得包含 libarrow 二进制文件的二进制 R 包

Graphic showing R and C++ logo inside the package icon

如果您想要更快的安装过程，并且默认情况下想要一个功能更全的构建，您可以从 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 包管理器：管理员指南以了解更多详细信息。

对于其他 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 源代码包

Graphic showing R logo in folder icon, then a plus sign, then C++ logo inside the package icon

另一种实现更快安装并启用所有关键功能的方法是使用我们托管的静态 libarrow 二进制文件。根据 allowlist，这些二进制文件在许多 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")

安装发布版本（不太容易）

Graphic showing R inside a folder icon, then a plus sign, then C++ logo inside a folder icon

安装 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` 二进制文件而不是从源代码构建	(unset)
`LIBARROW_DOWNLOAD`	设置为 `false` 以明确禁止获取 `libarrow` 二进制文件	(unset)
`LIBARROW_MINIMAL`	使用启用的最少功能构建	(unset)
`NOT_CRAN`	设置 `LIBARROW_BINARY=true` 和 `LIBARROW_MINIMAL=false`	`false`
`ARROW_R_DEV`	更详细的消息传递并重新生成一些代码	`false`
`ARROW_USE_PKG_CONFIG`	使用 `pkg-config` 搜索 `libarrow` 安装	`true`
`LIBARROW_DEBUG_DIR`	用于保存源构建日志的目录	(unset)
`CMAKE`	替代 CMake 路径	(unset)

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

LIBARROW_BINARY：默认情况下，在许多发行版上，或者如果明确设置为 true，该脚本将确定是否存在可与您的系统一起使用的预构建 libarrow。您可以将其设置为 false 以完全跳过此选项，或者可以指定与可用的二进制文件相对应的字符串“发行版-版本”，以覆盖此函数可能默认发现的内容。可能的值包括：“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_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 (RSPM) 上使用 RStudio Package Manager，并且您想使用此函数创建源包，请确保将 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 以告诉 configure 脚本不要查找 libarrow 的系统版本。（后者是 install_arrow() 的默认设置。）系统 libarrow 版本可用于所有 CRAN 版本，但不适用于 nightly 或 dev 版本，因此根据您正在安装的 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。

进一步阅读

要了解有关安装开发版本的信息，请参阅关于安装 nightly 构建的文章。
如果您正在为 Arrow 项目做出贡献，请参阅 Arrow R 开发者指南，以获取帮助您设置开发环境的资源。
Arrow 开发者可能还希望阅读对安装过程中运行的代码的更详细的讨论，这在安装详细信息文章中进行了描述。