在 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 時，您會獲得一個 R 二進位套件，其中包含 libarrow 的預編譯版本。安裝二進位檔案比從原始碼安裝容易得多，但 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")

請注意，使用者代理程式標頭必須如上述範例中指定。請查看 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 原始碼套件

實現更快安裝且啟用所有主要功能的另一種方法是使用我們託管的靜態 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 (RSPM) 上使用 RStudio 套件管理器，並且您想要使用此函數建立原始碼捆綁包，請確保將 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.dev.org.tw/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 套件無法載入，可能出現「undefined symbols」錯誤，請 回報問題。這很可能是編譯器不符，並且可以透過設定一些環境變數來指示 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 開發人員可能也希望閱讀更詳細的討論，內容關於安裝過程中執行的程式碼，詳見 安裝詳細資訊文章。