Serving Package Binaries#
The binary format of an R package is useful because an R user can install a binary package without compiling all of the package's source code. In some cases source packages can take hours to install. Additionally, compiling package binaries requires locating and installing system prerequisites. Package Manager binary support can eliminate this burden of waiting for packages to compile.
To check if Package Manager has a binary for a package, select a package and scroll down to "Binary File" to find a download link if a binary package is available. Next, click on the distribution or R version to change the desired package environment.
Traditionally, public CRAN mirrors have made binary packages available for the Windows and Mac operating systems. Package Manager provides precompiled binaries for CRAN packages for both Windows and Linux.
When enabled, Package Manager will serve the appropriate CRAN binaries to R users instead of the source packages, saving R users significant installation time. Binary packages are specific to the binary distribution and R versions used to generate them. Package Manager is careful to supply the correct binaries based on its configuration settings and the user's indicated distribution and version of R.
Additionally, Package Manager allows you to supplement local and git sources with your own precompiled binaries.
Binary distributions are sets of packages that have been built for a given platform that encompasses the operating system, architecture, and system library dependencies. By telling Package Manager which distribution you are installing to, it can ensure a binary is compatible with your environment and will display instructions on how to install any other dependencies you may need.
The usage of the term "distribution" here could potentially be confused as synonymous with "Linux distributions." Although similiar, the definition of binary distributions is more broadly used to help describe binary compatibility across environments.
CRAN Package Binaries#
Posit pre-compiles the majority of CRAN packages for a combination of R versions and distributions. Package Manager downloads the binaries from the Posit Package Service, respecting the same sync and download settings as the CRAN metadata.
The Posit Package Service builds binary packages using open source R binaries and Docker images. To ensure that the binary packages are compatible with your client systems, we recommend using the same R binaries or Docker images:
We provide best-effort support for archived package binaries for packages archived after October 9, 2017. We do not provide support for packages archived prior to October 9th, 2017.
CRAN Binary Availability#
Whether a binary can successfully be pre-compiled depends on several factors, including:
- R version
- Source (CRAN, Bioconductor, etc.)
- Compiler versions
Because of this, Package Manager may not serve pre-built binaries for all packages on all distributions. Some common reasons why a package may not have a binary are:
- A package depends on a Bioconductor package. Package Manager does not currently support binary packages from Bioconductor, notable packages include Seurat and WGCNA.
- A package depends on an uncatalogued system dependency. Refer to Missing System Dependencies for more information.
- A package depends on a newer compiler version or system library than available by default on the distribution being used.
If you've checked that the binary is supported and the UI reports no binary available for that distribution and R version, report the issue at Posit Community. Please provide information such as the package name, R version and distribution when reporting the issue. If you can tell that the problem is with compilation or system dependencies, including that info would also be helpful, but is not required.
Local and Git Binaries#
Package Manager allows you to supplement local and git sources with your own precompiled binaries. You can add binaries for any distribution supported by Package Manager. See Supported Operating Systems.
Precompiled R binary packages include metadata in the
identifies the R version and operating system on which the binary was compiled.
Since the metadata does not include information about the specific Linux
distribution that compiled the binary package, you must specify a distribution
when adding a binary package.
Package Manager currently supports supplementing only local and git sources with your own binary packages. You cannot add your own binaries to CRAN, Bioconductor, or PyPI sources. Package Manager does not support supplementing local and git sources with binary packages for macOS at this time.
Supported Operating Systems#
Package Manager supports binary packages for Windows and the following Linux distributions:
- Ubuntu 18.04 (Bionic)
- Ubuntu 20.04 (Focal)
- Ubuntu 22.04 (Jammy)
- CentOS/RHEL 7
- RHEL 8
- RHEL 9
- openSUSE 15.3, SLES 15 SP3
- openSUSE 15.4, SLES 15 SP4
When an operating system has reached its end of support, Package Manager will continue to serve binary packages for that operating system in perpetuity, but no longer provide new binary packages after several months. Refer to the Posit Platform Support page for the vendor end-of-support dates.
End of support distributions
The following Linux distributions have reached the end of support:
- Ubuntu 16.04 (Xenial)
- CentOS 8
- openSUSE 42.3, SLES 12 SP5
- openSUSE 15.1, SLES 15 SP1
- openSUSE 15.2, SLES 15 SP2
Package Manager does not currently support binary packages for Mac operating systems.
Supported R Versions#
Package Manager supports binary packages for the current R version and the four previous versions of R. For example, R 4.2 is the current version at the time of writing. That means that we support R 4.2 (current), 4.1, 4.0, 3.6, 3.5. Prior to R 4.1, we built against the latest available R version at the time of build. Beginning with R 4.1, we build against the oldest compatible patch release for a given minor version, so that our binaries should be compatible with any release within the minor release series (i.e. binaries should work for 4.1.0-4.1.X).
When an R version is no longer supported, Package Manager will continue to serve binary packages for that R version in perpetuity, but no longer provide new binary packages after several months.
Binaries for Other Package Manager Sources#
At this time, Package Manager provides binary packages for CRAN, curated CRAN, and CRAN snapshot sources. You can also supplement local and git sources with your own precompiled binary packages. Please contact firstname.lastname@example.org if you are interested in binary packages for Bioconductor or PyPI sources.
Binary Configuration Steps#
By default, Package Manager will enable binary repository URLs and
serve binary packages for the CRAN Source for Windows and all supported
Linux distributions. Administrators can restrict the distributions that
binaries are enabled for using the
Restricting the distributions for which binaries are enabled will also restrict the distributions for which you can upload your own binaries to supplement local and git sources.
To serve binaries for certain distributions only, use a comma-separated list of names, such as:
[Binaries] Distributions = "centos7, centos8"
To disable support for binary packages, use a blank value:
[Binaries] Distributions = ""
Adding Local and Git Binaries#
Package Manager allows you to supplement the source packages in local and git sources with your own precompiled binary packages. Adding a binary package to a local or git source is very similar to adding a source package.
R binary packages are built with
R CMD INSTALL. A binary package includes a
Built field in the
DESCRIPTION file. The
Built field includes
- the R version,
- the operating system, and
- the architecture (e.g.,
x86_64; not included for pure R packages)
Installing Binary Packages#
Use the command line interface to install binary
packages for local and git sources. The
rspm add binary
CLI command requires the following flags:
--source- The local or git source name.
--distribution- The distribution for the binary (e.g.,
bionic). You must specify a valid distribution.
--file-in- The binary file(s) to upload.
--replace- Required when a matching binary already exists in the source if you wish to replace it with a new binary.
Git sources automatically assign unique versions to each source package when building packages based on commits to a branch. The automatic version includes a suffix that is based on the current timestamp, which makes it difficult to upload precompiled binary packages for the git source. When you wish to upload binary packages for a git source, we recommend configuring the git builder to use tags. See Commits vs Tags for more details.
If you must upload binary packages for a git source when using a
commit-based git builder, consider using the
For examples of adding local and git binary packages, please refer to the Serve Local Binary Packages Quick Start Guide and the Serve Git Binary Packages Quick Start Guide.
R Configuration Steps (Linux)#
To use binary packages, an R user or Posit Workbench administrator should follow these steps to prepare and configure their environment:
Ensure that R is compatible with the precompiled binary packages. Binary packages distributed by Package Manager should be compatible with the default R on supported Linux distributions. However, the best way to ensure compatibility is to use the same R installation used to build the binary packages. Posit provides precompiled R binaries and Docker images for supported Linux distributions:
If using R 3.6 or a non-default download method such as "curl" or "wget", ensure that R correctly reports the R version and OS in the user agent header.
See Configuring the User Agent Header for instructions.
Install system dependencies used by your R packages. Although binary packages are precompiled, you may still need system dependencies used at runtime.
See System Dependency Detection for details on locating and installing system dependencies.
Using Linux Binary Packages#
For each Linux distribution that is enabled, Package Manager adds another repository URL to the repository Setup page on the web dashboard. For example, if Ubuntu 20.04 (Focal) is enabled, users have the option to pick between two repository URLs:
To access binaries, use the second URL when configuring the repo option in R. Alternatively, administrators can use the second URL when configuring Posit Workbench to use Package Manager.
When a user installs a package from the
__linux__ URL, Package Manager
will make a best-effort attempt to return a binary package. In cases where the
binary package is unavailable or unsupported on the user's binary distribution,
Package Manager falls back to serving the source version of the package.
Like the default URL, the enabled
__linux__ URL also supports
snapshots in addition to the
After determining the snapshot on the Setup page in the Package Manager UI, you may use a URL like this to configure the repo option in R:
To install binary packages, users should run
install.packages() using the
type argument (not
type = "binary"). For example, to install the
If the binary package installation succeeded, R should print a message like this:
* installing *binary* package 'dplyr' ...
If the binary package was unavailable or unsupported, Package Manager should fall back to serving a source package:
* installing *source* package 'dplyr' ...
Configuring the R User Agent Header#
Package Manager serves the appropriate binary package based on the
R version and OS in the user's
User-Agent request header.
R users or Posit Workbench admins may need to additionally configure the user agent in R if using:
- R 3.6 or later
- A non-default download method such as "curl" or "wget"
To determine if you need to configure the user agent header, you can run this diagnostic script. You can either download and run this script in R, or run it directly from an R console:
If your user agent is configured correctly, you should see a message like this:
Success! Your user agent is correctly configured.
If this diagnostic fails, R should be configured to include the R version and OS in the user agent header:
# Set the default HTTP user agent options(HTTPUserAgent = sprintf("R/%s R (%s)", getRversion(), paste(getRversion(), R.version["platform"], R.version["arch"], R.version["os"])))
To use binary packages with a non-default download method such as
"wget", R should be configured to include the R version and operating
system in the user agent header:
# Set the default HTTP user agent options(download.file.extra = sprintf("--header \"User-Agent: R (%s)\"", paste(getRversion(), R.version["platform"], R.version["arch"], R.version["os"])))
We recommend adding this to the site-wide startup file (
user startup file (
.Rprofile), so that R always starts with the correct
After configuring your user agent, you can re-run the diagnostic script to verify whether it is configured correctly by running this diagnostic script.
The Package Service Log provides a record of package installation requests to Package Manager. When enabled, administrators can use the Service Log to determine why a user received a source package when installing from a binary repository URL.
Package Manager also returns one or two HTTP response headers that can help explain what type of package was served:
X-Package-Type- indicates either binary or source
X-Package-Binary-Tag- indicates the R version and distribution associated with the binary that was served. This only appears when a binary is served.
For example, you can test on the Linux command line with a request like:
$ curl -H "User-Agent: R (3.5.3 x86_64-pc-linux-gnu x86_64 linux-gnu)" -I https://r-pkgs.example.com/our-cran/__linux__/focal/latest/src/contrib/A3_1.0.0.tar.gz << HTTP/1.1 200 OK << Content-Length: 87490 << Content-Type: application/x-gzip << X-Package-Binary-Tag: 3.5-focal << X-Package-Type: binary
Or at an R console:
> curlGetHeaders("https://r-pkgs.example.com/our-cran/__linux__/focal/latest/src/contrib/A3_1.0.0.tar.gz") # ... #  "X-Package-Binary-Tag: 3.5-focal\r\n" #  "X-Package-Type: binary\r\n"
R Configuration Steps (Windows)#
To use binary packages, an R user should follow these steps to prepare and configure their environment:
Ensure that R is compatible with the precompiled binary packages. Binary packages distributed by Package Manager should be compatible with the default R on Windows OSs.
Install system dependencies used by your R packages. Although binary packages are precompiled, you may still need system dependencies used at runtime.
For more information see the CRAN documentation for installing R packages on Windows.
Using Windows Binary Packages#
For Windows binary packages, users take advantage of the same URL they use for source packages. For example, if the
repository is called
our-cran, then users will want to use the following repository URL to install packages (from the
You'll see R print the same messages indicating if the user received a binary or source package from Package Manager.
If only the source package is available you'll sometimes see:
install.packages('example-package', repos='https://r-pkgs.example.com/our-cran/latest') # Package which is only available in source form, and may need # compilation of [example-system-dependency]: 'text2vec' # Do you want to attempt to install these from sources? (Yes/no/cancel)
This means additional system dependencies are required for the installation.
It is important to note that Package Manager makes a best effort to use the same compatibility requirements as CRAN. For more information see the CRAN documentation on installing R packages on Windows.