Serving Package Binaries#

Binary Packages#

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. Posit 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. 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 macOS operating systems. Package Manager provides precompiled binaries for CRAN packages for Windows, macOS, 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#

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.

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:

• Posit R Binaries
• Posit R Docker Images

CRAN Binary Availability#

Whether a binary can successfully be pre-compiled depends on several factors, including:

• Distribution
• 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 DESCRIPTION that 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.

Supported Operating Systems#

Package Manager supports binary packages for Windows, macOS, and the following Linux distributions:

• Ubuntu 20.04 (Focal)
• Ubuntu 22.04 (Jammy)
• Ubuntu 24.04 (Noble)
• Debian 11 (Bullseye)
• Debian 12 (Bookworm)
• RHEL 8
• RHEL 9
• openSUSE 15.5, SLES 15 SP5
• openSUSE 15.6, SLES 15 SP6

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.

Supported R Versions#

Package Manager supports binary packages for the current R version and the four previous versions of R. For example, R 4.4 is the current version at the time of writing. That means that we support R 4.4 (current), 4.3, 4.2, 4.1, 4.0. 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 Posit customer support (support@posit.co) 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, macOS, and all supported Linux distributions. Administrators can restrict the distributions that binaries are enabled for using the Binaries.Distributions configuration setting.

To serve binaries for certain distributions only, use a comma-separated list of names, such as:

[Binaries]
Distributions = "rhel8, rhel9, ubuntu2004, ubuntu2204"

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.

Requirements#

R binary packages are built with R CMD INSTALL. A binary package includes a special Built field in the DESCRIPTION file. The Built field includes information about

• 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., windows or jammy). You must specify a valid distribution.
• --path or --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 for R packages automatically assign unique versions to each source package when building packages based on commits to a branch. The automatic version includes a suffix 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. Review the Commits vs Tags section for more details.

Examples#

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)#

Prerequisites#

To use binary packages, an R user or Posit Workbench administrator should follow these steps to prepare and configure their environment:

1. 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:

   • Posit R Binaries
   • Posit R Docker Images

2. 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.

3. 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:

https://packagemanager.example.com/our-cran/latest
https://packagemanager.example.com/our-cran/__linux__/focal/latest

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 latest flag.

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:

https://packagemanager.example.com/our-cran/__linux__/rhel9/2022-04-07

To install binary packages, users should run install.packages() using the default type argument (not type = "binary"). For example, to install the dplyr package:

install.packages("dplyr")

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, run this diagnostic script. Download and run this script in R, or run it directly from an R console:

# User agent diagnostic script for Posit Package Manager binary packages

local({
  if (.Platform$OS.type != "unix" || Sys.info()["sysname"] == "Darwin") {
    message("Success! Posit Package Manager does not require additional configuration to install binary packages on macOS or Windows.")
    return(invisible())
  }

  dl_method <- getOption("download.file.method", "")
  dl_extra_args <- getOption("download.file.extra", "")
  user_agent <- getOption("HTTPUserAgent", "")

  if (dl_method == "") {
    dl_method <- if (isTRUE(capabilities("libcurl"))) "libcurl" else "internal"
  }

  default_ua <- sprintf("R (%s)", paste(getRversion(), R.version$platform, R.version$arch, R.version$os))

  instruction_template <- 'You must configure your HTTP user agent in R to install binary packages.

In your site-wide startup file (Rprofile.site) or user startup file (.Rprofile), add:

# Set default user agent
%s


Then restart your R session and run this diagnostic script again.
'

  message(c(
    sprintf("R installation path: %s\n", R.home()),
    sprintf("R version: %s\n", R.version.string),
    sprintf("OS version: %s\n", utils::sessionInfo()$running),
    sprintf("HTTPUserAgent: %s\n", user_agent),
    sprintf("Download method: %s\n", dl_method),
    sprintf("Download extra args: %s\n", dl_extra_args),
    "\n----------------------------\n"
  ))

  if (dl_method == "libcurl") {
    if (!grepl(default_ua, user_agent, fixed = TRUE) ||
        (getRversion() >= "3.6.0" && substr(user_agent, 1, 3) == "R (")) {
      config <- 'options(HTTPUserAgent = sprintf("R/%s R (%s)", getRversion(), paste(getRversion(), R.version["platform"], R.version["arch"], R.version["os"])))'
      message(sprintf(instruction_template, config))
      return(invisible())
    }
  } else if (dl_method %in% c("curl", "wget")) {
    if (!grepl(sprintf("--header \"User-Agent: %s\"", default_ua), dl_extra_args, fixed = TRUE)) {
      ua_arg <- "sprintf(\"--header \\\"User-Agent: R (%s)\\\"\", paste(getRversion(), R.version[\"platform\"], R.version[\"arch\"], R.version[\"os\"]))"
      if (dl_extra_args == "") {
        config <- sprintf("options(download.file.extra = %s)", ua_arg)
      } else {
        config <- sprintf("options(download.file.extra = paste(%s, %s))", shQuote(dl_extra_args), ua_arg)
      }
      message(sprintf(instruction_template, config))
      return(invisible())
    }
  }

  message("Success! Your user agent is correctly configured.")
})

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 curl or 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 (Rprofile.site) or user startup file (.Rprofile), so that R always starts with the correct configuration.

After configuring your user agent, you can re-run the diagnostic script to verify whether it is configured correctly by running this diagnostic script.

Troubleshooting#

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 such as:

$ curl -H "User-Agent: R (4.2.3 x86_64-pc-linux-gnu x86_64 linux-gnu)" -I https://packagemanager.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: 4.2-focal
<< X-Package-Type: binary

Or at an R console:

curlGetHeaders("https://packagemanager.example.com/our-cran/__linux__/focal/latest/src/contrib/A3_1.0.0.tar.gz")
# ...
# [10] "X-Package-Binary-Tag: 4.2-focal\r\n"
# [11] "X-Package-Type: binary\r\n"

R Configuration Steps (Windows and macOS)#

Prerequisites#

To use binary packages, an R user should follow these steps to prepare and configure their environment:

1. Install R from CRAN. Binary packages from Package Manager are intended to be compatible with CRAN's distribution of R, and may not work with other distributions of R (such as Homebrew's R on macOS).

2. Install system dependencies used by your R packages. Most binary packages on Windows and macOS come with bundled system dependencies and don't require additional software to use. However, some packages may still require runtime system dependencies, such as Java or JAGS.

For more information, refer to CRAN's documentation for installing R packages on Windows or installing R packages on macOS.

Using Windows and macOS Binary Packages#

For Windows and macOS 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 latest snapshot):

https://packagemanager.example.com/our-cran/latest

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://packagemanager.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, reference CRAN's documentation for installing R packages on Windows or installing R packages on macOS.