在 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 包管理器：管理员指南 以获取更多详细信息。

对于其他 Linux 发行版，要获取相关的 URL，您可以访问 RSPM 网站，点击“二进制文件”，然后选择您首选的发行版。

类似地，如果您使用 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 以完全跳过此选项，或者您可以指定一个与可用二进制文件对应的字符串“发行版-版本”来覆盖此函数可能默认发现的内容。可能的值为：“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，则配置脚本不会在您的系统上查找 Arrow 库，而是会尝试下载/构建它们。如果您在已安装的系统库和您要安装的 R 包的版本之间存在版本不匹配，请使用此选项。
• 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 版本，但不适用于夜间构建或开发版本，因此根据您正在安装的 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 开发人员可能还想阅读在安装过程中运行的代码的更详细讨论，该讨论在安装详细信息文章中进行了描述。