docs/dev/r/articles/developers/install_details.html - arrow-site - Git at Google

 <!DOCTYPE html>
 <!-- Generated by pkgdown: do not edit by hand --><html lang="en-US">
 <head>
 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
 <meta charset="utf-8">
 <meta http-equiv="X-UA-Compatible" content="IE=edge">
 <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
 <title>Installation details • Arrow R Package</title>
 <!-- favicons --><link rel="icon" type="image/png" sizes="96x96" href="../../favicon-96x96.png">
 <link rel="icon" type="”image/svg+xml”" href="../../favicon.svg">
 <link rel="apple-touch-icon" sizes="180x180" href="../../apple-touch-icon.png">
 <link rel="icon" sizes="any" href="../../favicon.ico">
 <link rel="manifest" href="../../site.webmanifest">
 <script src="../../deps/jquery-3.6.0/jquery-3.6.0.min.js"></script><meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
 <link href="../../deps/bootstrap-5.3.1/bootstrap.min.css" rel="stylesheet">
 <script src="../../deps/bootstrap-5.3.1/bootstrap.bundle.min.js"></script><link href="../../deps/font-awesome-6.5.2/css/all.min.css" rel="stylesheet">
 <link href="../../deps/font-awesome-6.5.2/css/v4-shims.min.css" rel="stylesheet">
 <script src="../../deps/headroom-0.11.0/headroom.min.js"></script><script src="../../deps/headroom-0.11.0/jQuery.headroom.min.js"></script><script src="../../deps/bootstrap-toc-1.0.1/bootstrap-toc.min.js"></script><script src="../../deps/clipboard.js-2.0.11/clipboard.min.js"></script><script src="../../deps/search-1.0.0/autocomplete.jquery.min.js"></script><script src="../../deps/search-1.0.0/fuse.min.js"></script><script src="../../deps/search-1.0.0/mark.min.js"></script><!-- pkgdown --><script src="../../pkgdown.js"></script><link href="../../extra.css" rel="stylesheet">
 <meta property="og:title" content="Installation details">
 <meta name="description" content="A low-level description of arrow installation intended for developers
 ">
 <meta property="og:description" content="A low-level description of arrow installation intended for developers
 ">
 <meta property="og:image" content="https://arrow.apache.org/img/arrow-logo_horizontal_black-txt_white-bg.png">
 <meta property="og:image:alt" content="Apache Arrow logo, displaying the triple chevron image adjacent to the text">
 <!-- Matomo --><script>
   var _paq = window._paq = window._paq || [];
   /* tracker methods like "setCustomDimension" should be called before "trackPageView" */
   /* We explicitly disable cookie tracking to avoid privacy issues */
   _paq.push(['disableCookies']);
   _paq.push(['trackPageView']);
   _paq.push(['enableLinkTracking']);
   (function() {
     var u="https://analytics.apache.org/";
     _paq.push(['setTrackerUrl', u+'matomo.php']);
     _paq.push(['setSiteId', '20']);
     var d=document, g=d.createElement('script'), s=d.getElementsByTagName('script')[0];
     g.async=true; g.src=u+'matomo.js'; s.parentNode.insertBefore(g,s);
   })();
 </script><!-- End Matomo Code --><!-- Kapa AI --><script async src="https://widget.kapa.ai/kapa-widget.bundle.js" data-website-id="9db461d5-ac77-4b3f-a5c5-75efa78339d2" data-project-name="Apache Arrow" data-project-color="#000000" data-project-logo="https://arrow.apache.org/img/arrow-logo_chevrons_white-txt_black-bg.png" data-modal-disclaimer="This is a custom LLM with access to all of [Arrow documentation](https://arrow.apache.org/docs/).  If you want an R-specific answer, please mention this in your question." data-consent-required="true" data-user-analytics-cookie-enabled="false" data-consent-screen-disclaimer="By clicking &quot;I agree, let's chat&quot;, you consent to the use of the AI assistant in accordance with kapa.ai's [Privacy Policy](https://www.kapa.ai/content/privacy-policy). This service uses reCAPTCHA, which requires your consent to Google's [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms). By proceeding, you explicitly agree to both kapa.ai's and Google's privacy policies."></script><!-- End Kapa AI -->
 </head>
 <body>
     <a href="#main" class="visually-hidden-focusable">Skip to contents</a>


     <nav class="navbar fixed-top navbar-dark navbar-expand-lg bg-black"><div class="container">

     <a class="navbar-brand me-2" href="../../index.html">Arrow R Package</a>

     <span class="version">
       <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">22.0.0.9000</small>
     </span>


     <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbar" aria-controls="navbar" aria-expanded="false" aria-label="Toggle navigation">
       <span class="navbar-toggler-icon"></span>
     </button>

     <div id="navbar" class="collapse navbar-collapse ms-3">
       <ul class="navbar-nav me-auto">
 <li class="nav-item"><a class="nav-link" href="../../articles/arrow.html">Get started</a></li>
 <li class="nav-item"><a class="nav-link" href="../../reference/index.html">Reference</a></li>
 <li class="active nav-item dropdown">
   <button class="nav-link dropdown-toggle" type="button" id="dropdown-articles" data-bs-toggle="dropdown" aria-expanded="false" aria-haspopup="true">Articles</button>
   <ul class="dropdown-menu" aria-labelledby="dropdown-articles">
 <li><hr class="dropdown-divider"></li>
     <li><h6 class="dropdown-header" data-toc-skip>Using the package</h6></li>
     <li><a class="dropdown-item" href="../../articles/read_write.html">Reading and writing data files</a></li>
     <li><a class="dropdown-item" href="../../articles/data_wrangling.html">Data analysis with dplyr syntax</a></li>
     <li><a class="dropdown-item" href="../../articles/dataset.html">Working with multi-file data sets</a></li>
     <li><a class="dropdown-item" href="../../articles/python.html">Integrating Arrow, Python, and R</a></li>
     <li><a class="dropdown-item" href="../../articles/fs.html">Using cloud storage (S3, GCS)</a></li>
     <li><a class="dropdown-item" href="../../articles/flight.html">Connecting to a Flight server</a></li>
     <li><hr class="dropdown-divider"></li>
     <li><h6 class="dropdown-header" data-toc-skip>Arrow concepts</h6></li>
     <li><a class="dropdown-item" href="../../articles/data_objects.html">Data objects</a></li>
     <li><a class="dropdown-item" href="../../articles/data_types.html">Data types</a></li>
     <li><a class="dropdown-item" href="../../articles/metadata.html">Metadata</a></li>
     <li><hr class="dropdown-divider"></li>
     <li><h6 class="dropdown-header" data-toc-skip>Installation</h6></li>
     <li><a class="dropdown-item" href="../../articles/install.html">Installing on Linux</a></li>
     <li><a class="dropdown-item" href="../../articles/install_nightly.html">Installing development versions</a></li>
     <li><hr class="dropdown-divider"></li>
     <li><a class="dropdown-item" href="../../articles/index.html">More articles...</a></li>
   </ul>
 </li>
 <li class="nav-item"><a class="nav-link" href="../../news/index.html">Changelog</a></li>
       </ul>
 <form class="form-inline my-2 my-lg-0" role="search">
         <input type="search" class="form-control me-sm-2" aria-label="Toggle navigation" name="search-input" data-search-index="../../search.json" id="search-input" placeholder="" autocomplete="off">
 </form>

       <ul class="navbar-nav">
 <li class="nav-item"><a class="external-link nav-link" href="https://github.com/apache/arrow/" aria-label="GitHub"><span class="fa fab fa-github fa-lg"></span></a></li>
       </ul>
 </div>


   </div>
 </nav><div class="container template-article">


 <div class="row">
   <main id="main" class="col-md-9"><div class="page-header">

       <h1>Installation details</h1>


       <small class="dont-index">Source: <a href="https://github.com/apache/arrow/blob/main/r/vignettes/developers/install_details.Rmd" class="external-link"><code>vignettes/developers/install_details.Rmd</code></a></small>
       <div class="d-none name"><code>install_details.Rmd</code></div>
     </div>


 <p>This document is intended specifically for arrow <em>developers</em>
 who wish to know more about these scripts. If you are an arrow
 <em>user</em> looking for help with installing arrow, please see <a href="../install.html">the installation guide</a></p>
 <p>The arrow R package requires that Arrow C++ library (also known as
 libarrow) to be installed in order to work properly. There are a number
 of different ways in which libarrow could be installed:</p>
 <ul>
 <li>as part of the R package installation process</li>
 <li>a system package</li>
 <li>a library you’ve built yourself outside of the context of installing
 the R package</li>
 </ul>
 <p>Below, we discuss each of these setups in turn.</p>
 <div class="section level2">
 <h2 id="installing-libarrow-during-r-package-installation">Installing libarrow during R package installation<a class="anchor" aria-label="anchor" href="#installing-libarrow-during-r-package-installation"></a>
 </h2>
 <p>There are a number of scripts that are triggered when
 <code>R CMD INSTALL .</code> is run and for Arrow users, these should
 all just work without configuration and pull in the most complete pieces
 (e.g. official binaries that we host). One of the jobs of these scripts
 is to work out if libarrow is installed, and if not, install it.</p>
 <p>An overview of these scripts is shown below:</p>
 <ul>
 <li><p><code>configure</code> and <code>configure.win</code> - these
 scripts are triggered during <code>R CMD INSTALL .</code> on non-Windows
 and Windows platforms, respectively. They handle finding the libarrow,
 setting up the build variables necessary, and writing the package
 Makevars file that is used to compile the C++ code in the R
 package.</p></li>
 <li><p><code>tools/nixlibs.R</code> - this script is called by
 <code>configure</code> on Linux and macOS (or on any non-windows OS with
 the environment variable <code>FORCE_BUNDLED_BUILD=true</code>). On
 windows this script is called by <code>configure.win</code> when
 environment variable <code>ARROW_HOME</code> is not set. It looks for an
 existing libarrow installation, and if it can’t find one downloads an
 appropriate libarrow binary. On non-windows if no binary could be found,
 the script sets up the build process for our bundled builds (which is
 the default on linux) and checks for dependencies.</p></li>
 <li><p><code>inst/build_arrow_static.sh</code> - called by
 <code>tools/nixlibs.R</code> when libarrow needs to be built. It builds
 libarrow for a bundled, static build, and mirrors the steps described in
 the <a href="./setup.html">Arrow R developer guide</a> This build script
 is also what is used to generate our prebuilt binaries.</p></li>
 </ul>
 <p>The actions taken by these scripts to resolve dependencies and
 install the correct components are described below.</p>
 <div class="section level3">
 <h3 id="how-the-r-package-finds-libarrow">How the R package finds libarrow<a class="anchor" aria-label="anchor" href="#how-the-r-package-finds-libarrow"></a>
 </h3>
 <div class="section level4">
 <h4 id="windows">Windows<a class="anchor" aria-label="anchor" href="#windows"></a>
 </h4>
 <p>The diagram below shows how the R package finds a libarrow
 installation on Windows.</p>
 <p><img src="install_diagram_windows.png" class="r-plt" alt="Flowchart of libarrow installation on Windows systems - find full descriptions in sections 'Checking for existing libarrow installations' and 'Downloading libarrow' below" width="70%"></p>
 <div class="section level5">
 <h5 id="checking-for-existing-libarrow-installations">Checking for existing libarrow installations<a class="anchor" aria-label="anchor" href="#checking-for-existing-libarrow-installations"></a>
 </h5>
 <p>When you install the arrow R package on Windows, if the
 <code>ARROW_HOME</code> environment variable has not been set, the
 install script looks for an existing libarrow installation. If this
 cannot be find, it then checks whether the <code>R_WINLIB_LOCAL</code>
 environment variable has been set to point to a local installation.</p>
 </div>
 <div class="section level5">
 <h5 id="downloading-libarrow">Downloading libarrow<a class="anchor" aria-label="anchor" href="#downloading-libarrow"></a>
 </h5>
 <p>If no existing libarrow installations can be found, the script
 proceeds to try to download the required version of libarrow, first from
 the nightly builds repository and then from Rwinlib. The script first
 tries to find a version of libarrow which is matches the most components
 according to semantic versioning, and in the case of a failure becomes
 less specific (i.e. if there are no binaries found for version 0.14.1.1,
 then try to find one for 0.14.1).</p>
 </div>
 </div>
 <div class="section level4">
 <h4 id="non-windows">Non-Windows<a class="anchor" aria-label="anchor" href="#non-windows"></a>
 </h4>
 <p>On Linux and macOS, the core logic is:</p>
 <ol style="list-style-type: decimal">
 <li>If <code>FORCE_BUNDLED_BUILD=true</code>, skip to step 3.</li>
 <li>Find libarrow on the system. If it is present, make sure that its
 version is compatible with the R package.</li>
 <li>If no suitable libarrow is found, download it (where allowed) or
 build it from source.</li>
 <li>Determine what features this libarrow has and what other flags it
 requires, and set them in <code>src/Makevars</code> for use when
 compiling the bindings.</li>
 </ol>
 <div class="section level5">
 <h5 id="finding-libarrow-on-the-system">Finding libarrow on the system<a class="anchor" aria-label="anchor" href="#finding-libarrow-on-the-system"></a>
 </h5>
 <p>The <code>configure</code> script will look for libarrow in three
 places:</p>
 <ol style="list-style-type: decimal">
 <li>The path in environment variable <code>ARROW_HOME</code>, if
 set</li>
 <li>Whatever <code>pkg-config</code> finds, unless
 <code>ARROW_USE_PKG_CONFIG=false</code>
 </li>
 <li>Homebrew, if you have done
 <code>brew install apache-arrow</code>
 </li>
 </ol>
 <p>If a libarrow build is found, it will then check that the version of
 that C++ library matches that of the R package. If the versions do not
 match, like when you’ve installed a system package for a release version
 but you have a development version of the R package, that libarrow will
 not be used. If both the C++ library and R package are on development
 versions, you will see a warning message advising you that if you do
 have trouble, you should ensure that the C++ library was built from the
 same commit as the R package, as development version numbers do not
 change with every commit.</p>
 </div>
 <div class="section level5">
 <h5 id="prebuilt-binaries">Prebuilt binaries<a class="anchor" aria-label="anchor" href="#prebuilt-binaries"></a>
 </h5>
 <p>If libarrow is not found on the system, the R package installation
 script will next attempt to download prebuilt libarrow binaries that
 match your both your local operating system, required dependencies
 (e.g. openssl version) and arrow R package version.</p>
 <p>These are used automatically on many Linux distributions (x86_64
 architecture only), according to the <a href="https://github.com/apache/arrow/blob/main/r/tools/nixlibs-allowlist.txt" class="external-link">allowlist</a>.
 If your distribution isn’t in the list, you can opt-in by setting the
 <code>NOT_CRAN</code> environment variable before you call
 <code><a href="https://rdrr.io/r/utils/install.packages.html" class="external-link">install.packages()</a></code>. If found, they will be downloaded and
 bundled when your R package compiles.</p>
 </div>
 <div class="section level5">
 <h5 id="building-from-source">Building from source<a class="anchor" aria-label="anchor" href="#building-from-source"></a>
 </h5>
 <p>If no suitable libarrow binary is found, it will attempt to build it
 locally. First, it will also look to see if you are in a checkout of the
 <code>apache/arrow</code> git repository and thus have the libarrow
 source files there. Otherwise, it builds from the source files included
 in the package. Depending on your system, building libarrow from source
 may be slow. If libarrow is built from source,
 <code>inst/build_arrow_static.sh</code> is executed.</p>
 </div>
 </div>
 </div>
 </div>
 <div class="section level2">
 <h2 id="using-the-r-package-with-libarrow-installed-as-a-system-package">Using the R package with libarrow installed as a system package<a class="anchor" aria-label="anchor" href="#using-the-r-package-with-libarrow-installed-as-a-system-package"></a>
 </h2>
 <p>If you are authorized to install system packages and you’re
 installing a CRAN release, you may want to use the official Apache Arrow
 release packages corresponding to the R package version via software
 distribution tools such as <code>apt</code> or <code>yum</code> (though
 there are some drawbacks: see the <a href="../install.html#troubleshooting">“Troubleshooting” section in the
 main installation docs</a>). See the <a href="https://arrow.apache.org/install/" class="external-link">Arrow project installation
 page</a> to find pre-compiled binary packages for some common Linux
 distributions, including Debian, Ubuntu, and CentOS.</p>
 <p>If you are a developer contributing to the R package, system libarrow
 packages won’t be useful because the versions will not match.</p>
 </div>
 <div class="section level2">
 <h2 id="using-the-r-package-with-an-existing-libarrow-build">Using the R package with an existing libarrow build<a class="anchor" aria-label="anchor" href="#using-the-r-package-with-an-existing-libarrow-build"></a>
 </h2>
 <p>This setup is much more common for arrow developers, who may be
 needing to make changes to both the R package and libarrow source code.
 See the <a href="./setup.html">developer setup docs</a> for more
 information.</p>
 </div>
   </main><aside class="col-md-3"><nav id="toc" aria-label="Table of contents"><h2>On this page</h2>
     </nav></aside>
 </div>


     <footer><div class="pkgdown-footer-left">
   <p><a href="https://arrow.apache.org/docs/r/versions.html">Older versions of these docs</a></p>
 </div>

 <div class="pkgdown-footer-right">
   <p>Site built with <a href="https://pkgdown.r-lib.org/" class="external-link">pkgdown</a> 2.2.0.</p>
 </div>

     </footer>
 </div>


   </body>
 </html>
	<!DOCTYPE html>
	<!-- Generated by pkgdown: do not edit by hand --><html lang="en-US">
	<head>
	<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
	<meta charset="utf-8">
	<meta http-equiv="X-UA-Compatible" content="IE=edge">
	<meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
	<title>Installation details • Arrow R Package</title>
	<!-- favicons --><link rel="icon" type="image/png" sizes="96x96" href="../../favicon-96x96.png">
	<link rel="icon" type="”image/svg+xml”" href="../../favicon.svg">
	<link rel="apple-touch-icon" sizes="180x180" href="../../apple-touch-icon.png">
	<link rel="icon" sizes="any" href="../../favicon.ico">
	<link rel="manifest" href="../../site.webmanifest">
	<script src="../../deps/jquery-3.6.0/jquery-3.6.0.min.js"></script><meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
	<link href="../../deps/bootstrap-5.3.1/bootstrap.min.css" rel="stylesheet">
	<script src="../../deps/bootstrap-5.3.1/bootstrap.bundle.min.js"></script><link href="../../deps/font-awesome-6.5.2/css/all.min.css" rel="stylesheet">
	<link href="../../deps/font-awesome-6.5.2/css/v4-shims.min.css" rel="stylesheet">
	<script src="../../deps/headroom-0.11.0/headroom.min.js"></script><script src="../../deps/headroom-0.11.0/jQuery.headroom.min.js"></script><script src="../../deps/bootstrap-toc-1.0.1/bootstrap-toc.min.js"></script><script src="../../deps/clipboard.js-2.0.11/clipboard.min.js"></script><script src="../../deps/search-1.0.0/autocomplete.jquery.min.js"></script><script src="../../deps/search-1.0.0/fuse.min.js"></script><script src="../../deps/search-1.0.0/mark.min.js"></script><!-- pkgdown --><script src="../../pkgdown.js"></script><link href="../../extra.css" rel="stylesheet">
	<meta property="og:title" content="Installation details">
	<meta name="description" content="A low-level description of arrow installation intended for developers
	">
	<meta property="og:description" content="A low-level description of arrow installation intended for developers
	">
	<meta property="og:image" content="https://arrow.apache.org/img/arrow-logo_horizontal_black-txt_white-bg.png">
	<meta property="og:image:alt" content="Apache Arrow logo, displaying the triple chevron image adjacent to the text">
	<!-- Matomo --><script>
	var _paq = window._paq = window._paq \|\| [];
	/* tracker methods like "setCustomDimension" should be called before "trackPageView" */
	/* We explicitly disable cookie tracking to avoid privacy issues */
	_paq.push(['disableCookies']);
	_paq.push(['trackPageView']);
	_paq.push(['enableLinkTracking']);
	(function() {
	var u="https://analytics.apache.org/";
	_paq.push(['setTrackerUrl', u+'matomo.php']);
	_paq.push(['setSiteId', '20']);
	var d=document, g=d.createElement('script'), s=d.getElementsByTagName('script')[0];
	g.async=true; g.src=u+'matomo.js'; s.parentNode.insertBefore(g,s);
	})();
	</script><!-- End Matomo Code --><!-- Kapa AI --><script async src="https://widget.kapa.ai/kapa-widget.bundle.js" data-website-id="9db461d5-ac77-4b3f-a5c5-75efa78339d2" data-project-name="Apache Arrow" data-project-color="#000000" data-project-logo="https://arrow.apache.org/img/arrow-logo_chevrons_white-txt_black-bg.png" data-modal-disclaimer="This is a custom LLM with access to all of [Arrow documentation](https://arrow.apache.org/docs/). If you want an R-specific answer, please mention this in your question." data-consent-required="true" data-user-analytics-cookie-enabled="false" data-consent-screen-disclaimer="By clicking "I agree, let's chat", you consent to the use of the AI assistant in accordance with kapa.ai's [Privacy Policy](https://www.kapa.ai/content/privacy-policy). This service uses reCAPTCHA, which requires your consent to Google's [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms). By proceeding, you explicitly agree to both kapa.ai's and Google's privacy policies."></script><!-- End Kapa AI -->
	</head>
	<body>
	<a href="#main" class="visually-hidden-focusable">Skip to contents</a>


	<nav class="navbar fixed-top navbar-dark navbar-expand-lg bg-black"><div class="container">

	<a class="navbar-brand me-2" href="../../index.html">Arrow R Package</a>

	<span class="version">
	<small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">22.0.0.9000</small>
	</span>


	<button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbar" aria-controls="navbar" aria-expanded="false" aria-label="Toggle navigation">
	<span class="navbar-toggler-icon"></span>
	</button>

	<div id="navbar" class="collapse navbar-collapse ms-3">
	<ul class="navbar-nav me-auto">
	<li class="nav-item"><a class="nav-link" href="../../articles/arrow.html">Get started</a></li>
	<li class="nav-item"><a class="nav-link" href="../../reference/index.html">Reference</a></li>
	<li class="active nav-item dropdown">
	<button class="nav-link dropdown-toggle" type="button" id="dropdown-articles" data-bs-toggle="dropdown" aria-expanded="false" aria-haspopup="true">Articles</button>
	<ul class="dropdown-menu" aria-labelledby="dropdown-articles">
	<li><hr class="dropdown-divider"></li>
	<li><h6 class="dropdown-header" data-toc-skip>Using the package</h6></li>
	<li><a class="dropdown-item" href="../../articles/read_write.html">Reading and writing data files</a></li>
	<li><a class="dropdown-item" href="../../articles/data_wrangling.html">Data analysis with dplyr syntax</a></li>
	<li><a class="dropdown-item" href="../../articles/dataset.html">Working with multi-file data sets</a></li>
	<li><a class="dropdown-item" href="../../articles/python.html">Integrating Arrow, Python, and R</a></li>
	<li><a class="dropdown-item" href="../../articles/fs.html">Using cloud storage (S3, GCS)</a></li>
	<li><a class="dropdown-item" href="../../articles/flight.html">Connecting to a Flight server</a></li>
	<li><hr class="dropdown-divider"></li>
	<li><h6 class="dropdown-header" data-toc-skip>Arrow concepts</h6></li>
	<li><a class="dropdown-item" href="../../articles/data_objects.html">Data objects</a></li>
	<li><a class="dropdown-item" href="../../articles/data_types.html">Data types</a></li>
	<li><a class="dropdown-item" href="../../articles/metadata.html">Metadata</a></li>
	<li><hr class="dropdown-divider"></li>
	<li><h6 class="dropdown-header" data-toc-skip>Installation</h6></li>
	<li><a class="dropdown-item" href="../../articles/install.html">Installing on Linux</a></li>
	<li><a class="dropdown-item" href="../../articles/install_nightly.html">Installing development versions</a></li>
	<li><hr class="dropdown-divider"></li>
	<li><a class="dropdown-item" href="../../articles/index.html">More articles...</a></li>
	</ul>
	</li>
	<li class="nav-item"><a class="nav-link" href="../../news/index.html">Changelog</a></li>
	</ul>
	<form class="form-inline my-2 my-lg-0" role="search">
	<input type="search" class="form-control me-sm-2" aria-label="Toggle navigation" name="search-input" data-search-index="../../search.json" id="search-input" placeholder="" autocomplete="off">
	</form>

	<ul class="navbar-nav">
	<li class="nav-item"><a class="external-link nav-link" href="https://github.com/apache/arrow/" aria-label="GitHub"><span class="fa fab fa-github fa-lg"></span></a></li>
	</ul>
	</div>


	</div>
	</nav><div class="container template-article">




	<div class="row">
	<main id="main" class="col-md-9"><div class="page-header">

	<h1>Installation details</h1>


	<small class="dont-index">Source: <a href="https://github.com/apache/arrow/blob/main/r/vignettes/developers/install_details.Rmd" class="external-link"><code>vignettes/developers/install_details.Rmd</code></a></small>
	<div class="d-none name"><code>install_details.Rmd</code></div>
	</div>



	<p>This document is intended specifically for arrow <em>developers</em>
	who wish to know more about these scripts. If you are an arrow
	<em>user</em> looking for help with installing arrow, please see <a href="../install.html">the installation guide</a></p>
	<p>The arrow R package requires that Arrow C++ library (also known as
	libarrow) to be installed in order to work properly. There are a number
	of different ways in which libarrow could be installed:</p>
	<ul>
	<li>as part of the R package installation process</li>
	<li>a system package</li>
	<li>a library you’ve built yourself outside of the context of installing
	the R package</li>
	</ul>
	<p>Below, we discuss each of these setups in turn.</p>
	<div class="section level2">
	<h2 id="installing-libarrow-during-r-package-installation">Installing libarrow during R package installation<a class="anchor" aria-label="anchor" href="#installing-libarrow-during-r-package-installation"></a>
	</h2>
	<p>There are a number of scripts that are triggered when
	<code>R CMD INSTALL .</code> is run and for Arrow users, these should
	all just work without configuration and pull in the most complete pieces
	(e.g. official binaries that we host). One of the jobs of these scripts
	is to work out if libarrow is installed, and if not, install it.</p>
	<p>An overview of these scripts is shown below:</p>
	<ul>
	<li><p><code>configure</code> and <code>configure.win</code> - these
	scripts are triggered during <code>R CMD INSTALL .</code> on non-Windows
	and Windows platforms, respectively. They handle finding the libarrow,
	setting up the build variables necessary, and writing the package
	Makevars file that is used to compile the C++ code in the R
	package.</p></li>
	<li><p><code>tools/nixlibs.R</code> - this script is called by
	<code>configure</code> on Linux and macOS (or on any non-windows OS with
	the environment variable <code>FORCE_BUNDLED_BUILD=true</code>). On
	windows this script is called by <code>configure.win</code> when
	environment variable <code>ARROW_HOME</code> is not set. It looks for an
	existing libarrow installation, and if it can’t find one downloads an
	appropriate libarrow binary. On non-windows if no binary could be found,
	the script sets up the build process for our bundled builds (which is
	the default on linux) and checks for dependencies.</p></li>
	<li><p><code>inst/build_arrow_static.sh</code> - called by
	<code>tools/nixlibs.R</code> when libarrow needs to be built. It builds
	libarrow for a bundled, static build, and mirrors the steps described in
	the <a href="./setup.html">Arrow R developer guide</a> This build script
	is also what is used to generate our prebuilt binaries.</p></li>
	</ul>
	<p>The actions taken by these scripts to resolve dependencies and
	install the correct components are described below.</p>
	<div class="section level3">
	<h3 id="how-the-r-package-finds-libarrow">How the R package finds libarrow<a class="anchor" aria-label="anchor" href="#how-the-r-package-finds-libarrow"></a>
	</h3>
	<div class="section level4">
	<h4 id="windows">Windows<a class="anchor" aria-label="anchor" href="#windows"></a>
	</h4>
	<p>The diagram below shows how the R package finds a libarrow
	installation on Windows.</p>
	<p><img src="install_diagram_windows.png" class="r-plt" alt="Flowchart of libarrow installation on Windows systems - find full descriptions in sections 'Checking for existing libarrow installations' and 'Downloading libarrow' below" width="70%"></p>
	<div class="section level5">
	<h5 id="checking-for-existing-libarrow-installations">Checking for existing libarrow installations<a class="anchor" aria-label="anchor" href="#checking-for-existing-libarrow-installations"></a>
	</h5>
	<p>When you install the arrow R package on Windows, if the
	<code>ARROW_HOME</code> environment variable has not been set, the
	install script looks for an existing libarrow installation. If this
	cannot be find, it then checks whether the <code>R_WINLIB_LOCAL</code>
	environment variable has been set to point to a local installation.</p>
	</div>
	<div class="section level5">
	<h5 id="downloading-libarrow">Downloading libarrow<a class="anchor" aria-label="anchor" href="#downloading-libarrow"></a>
	</h5>
	<p>If no existing libarrow installations can be found, the script
	proceeds to try to download the required version of libarrow, first from
	the nightly builds repository and then from Rwinlib. The script first
	tries to find a version of libarrow which is matches the most components
	according to semantic versioning, and in the case of a failure becomes
	less specific (i.e. if there are no binaries found for version 0.14.1.1,
	then try to find one for 0.14.1).</p>
	</div>
	</div>
	<div class="section level4">
	<h4 id="non-windows">Non-Windows<a class="anchor" aria-label="anchor" href="#non-windows"></a>
	</h4>
	<p>On Linux and macOS, the core logic is:</p>
	<ol style="list-style-type: decimal">
	<li>If <code>FORCE_BUNDLED_BUILD=true</code>, skip to step 3.</li>
	<li>Find libarrow on the system. If it is present, make sure that its
	version is compatible with the R package.</li>
	<li>If no suitable libarrow is found, download it (where allowed) or
	build it from source.</li>
	<li>Determine what features this libarrow has and what other flags it
	requires, and set them in <code>src/Makevars</code> for use when
	compiling the bindings.</li>
	</ol>
	<div class="section level5">
	<h5 id="finding-libarrow-on-the-system">Finding libarrow on the system<a class="anchor" aria-label="anchor" href="#finding-libarrow-on-the-system"></a>
	</h5>
	<p>The <code>configure</code> script will look for libarrow in three
	places:</p>
	<ol style="list-style-type: decimal">
	<li>The path in environment variable <code>ARROW_HOME</code>, if
	set</li>
	<li>Whatever <code>pkg-config</code> finds, unless
	<code>ARROW_USE_PKG_CONFIG=false</code>
	</li>
	<li>Homebrew, if you have done
	<code>brew install apache-arrow</code>
	</li>
	</ol>
	<p>If a libarrow build is found, it will then check that the version of
	that C++ library matches that of the R package. If the versions do not
	match, like when you’ve installed a system package for a release version
	but you have a development version of the R package, that libarrow will
	not be used. If both the C++ library and R package are on development
	versions, you will see a warning message advising you that if you do
	have trouble, you should ensure that the C++ library was built from the
	same commit as the R package, as development version numbers do not
	change with every commit.</p>
	</div>
	<div class="section level5">
	<h5 id="prebuilt-binaries">Prebuilt binaries<a class="anchor" aria-label="anchor" href="#prebuilt-binaries"></a>
	</h5>
	<p>If libarrow is not found on the system, the R package installation
	script will next attempt to download prebuilt libarrow binaries that
	match your both your local operating system, required dependencies
	(e.g. openssl version) and arrow R package version.</p>
	<p>These are used automatically on many Linux distributions (x86_64
	architecture only), according to the <a href="https://github.com/apache/arrow/blob/main/r/tools/nixlibs-allowlist.txt" class="external-link">allowlist</a>.
	If your distribution isn’t in the list, you can opt-in by setting the
	<code>NOT_CRAN</code> environment variable before you call
	<code><a href="https://rdrr.io/r/utils/install.packages.html" class="external-link">install.packages()</a></code>. If found, they will be downloaded and
	bundled when your R package compiles.</p>
	</div>
	<div class="section level5">
	<h5 id="building-from-source">Building from source<a class="anchor" aria-label="anchor" href="#building-from-source"></a>
	</h5>
	<p>If no suitable libarrow binary is found, it will attempt to build it
	locally. First, it will also look to see if you are in a checkout of the
	<code>apache/arrow</code> git repository and thus have the libarrow
	source files there. Otherwise, it builds from the source files included
	in the package. Depending on your system, building libarrow from source
	may be slow. If libarrow is built from source,
	<code>inst/build_arrow_static.sh</code> is executed.</p>
	</div>
	</div>
	</div>
	</div>
	<div class="section level2">
	<h2 id="using-the-r-package-with-libarrow-installed-as-a-system-package">Using the R package with libarrow installed as a system package<a class="anchor" aria-label="anchor" href="#using-the-r-package-with-libarrow-installed-as-a-system-package"></a>
	</h2>
	<p>If you are authorized to install system packages and you’re
	installing a CRAN release, you may want to use the official Apache Arrow
	release packages corresponding to the R package version via software
	distribution tools such as <code>apt</code> or <code>yum</code> (though
	there are some drawbacks: see the <a href="../install.html#troubleshooting">“Troubleshooting” section in the
	main installation docs</a>). See the <a href="https://arrow.apache.org/install/" class="external-link">Arrow project installation
	page</a> to find pre-compiled binary packages for some common Linux
	distributions, including Debian, Ubuntu, and CentOS.</p>
	<p>If you are a developer contributing to the R package, system libarrow
	packages won’t be useful because the versions will not match.</p>
	</div>
	<div class="section level2">
	<h2 id="using-the-r-package-with-an-existing-libarrow-build">Using the R package with an existing libarrow build<a class="anchor" aria-label="anchor" href="#using-the-r-package-with-an-existing-libarrow-build"></a>
	</h2>
	<p>This setup is much more common for arrow developers, who may be
	needing to make changes to both the R package and libarrow source code.
	See the <a href="./setup.html">developer setup docs</a> for more
	information.</p>
	</div>
	</main><aside class="col-md-3"><nav id="toc" aria-label="Table of contents"><h2>On this page</h2>
	</nav></aside>
	</div>



	<footer><div class="pkgdown-footer-left">
	<p><a href="https://arrow.apache.org/docs/r/versions.html">Older versions of these docs</a></p>
	</div>

	<div class="pkgdown-footer-right">
	<p>Site built with <a href="https://pkgdown.r-lib.org/" class="external-link">pkgdown</a> 2.2.0.</p>
	</div>

	</footer>
	</div>





	</body>
	</html>