Serving Package Binaries

Binary Packages

Installing an R package as a binary allows users to avoid compiling source code, which can be time-consuming and may require installing additional system dependencies. Some source packages can take hours to build, but Package Manager’s binary support eliminates this wait and simplifies package installation.

Historically, CRAN has provided binary packages for Windows and macOS only for the two most recent R versions, and only for the latest version of each package. Package Manager extends this by providing precompiled CRAN binaries for Windows, macOS, and Linux, covering the five most recent R versions and up to four years of historical package releases.

Additionally, Package Manager lets you supplement local and Git sources with your own precompiled binaries.

Binary Distributions

Binary distributions are collections of packages built for a specific platform, defined by the operating system, architecture, and system library dependencies. By specifying your target distribution in Package Manager, you ensure that the binaries provided are compatible with your environment. Package Manager will also display instructions for installing any additional required dependencies.

Note

The term “distribution” in this context refers to binary compatibility across different environments, not just Linux distributions. While related, “binary distribution” is a broader concept that encompasses compatibility across operating systems, architectures, and system libraries.

CRAN Package Binaries

Posit builds CRAN package binaries as part of the daily snapshot process. When a package is updated, Posit builds new binaries for that package and also rebuilds any dependent packages that use LinkingTo, ensuring that all packages remain compatible within a snapshot. Snapshots are only published when all binaries are available, so users can always install updated packages without needing to compile from source.

Package Manager instances then synchronize and download these binaries from the Posit Package Service, using the same sync and download settings as CRAN metadata.

For Linux, Posit builds binary packages using the Posit R Binaries. While these binaries are intended to be compatible with most R installations, we recommend using the Posit R binaries to ensure the best compatibility with Package Manager’s precompiled binaries. System libraries are sourced from standard Linux distributions, following the public catalog in the System Requirements for R Packages database.

For Windows and macOS, Posit uses the same toolchains and system libraries to build binary packages as used by CRAN. This ensures that the binaries are compatible with the R installations provided by CRAN.

CRAN Binary Availability

To determine if a binary is available for a package, navigate to the package in the web UI and look for the Binary File download link. You can adjust the distribution or R version to match your environment. Note that binary availability is only shown for the latest version of each package.

Whether a binary can successfully be built depends on several factors, including:

  • Distribution
  • R version
  • Architecture
  • Source (CRAN, Bioconductor, etc.)
  • Compiler versions

Because of this, Package Manager may not serve precompiled 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, R version, and architecture, 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.

Note

Posit provides best-effort support for archived package binaries for packages archived after October 9, 2017. Packages archived before this date are not supported.

CRAN Binary Security

Posit maintains a secure package build infrastructure to help protect users. All binary packages are built using a toolchain that is regularly updated with the latest security patches. When critical security patches are released, Posit rebuilds all affected packages, including those from older R versions and historical snapshots. Updated packages are made available immediately, but users must reinstall packages to receive the latest, secure versions.

On Linux systems, R packages typically dynamically link to system libraries provided by the Linux distribution. This means that security updates to these libraries are automatically applied when the system libraries are updated, without requiring users to reinstall the R package itself.

However, on Windows, macOS, and with portable Linux binary packages, R packages usually bundle their own system libraries. In these cases, users must reinstall the R package to receive security updates for the bundled libraries.

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, and any R version or architecture regardless of whether it is officially supported by Package Manager.

Note

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.

Supported Distributions and Architectures

Package Manager supports binary packages for the following distributions and architectures:

Distribution Architectures
Windows x86_64
macOS x86_64, ARM64
Ubuntu 22.04 (Jammy) x86_64
Ubuntu 24.04 (Noble) x86_64, ARM64
Debian 12 (Bookworm) x86_64
RHEL 8 x86_64
RHEL 9 x86_64, ARM64
RHEL 10 x86_64, ARM64
openSUSE 15.6, SLES 15 SP6 x86_64
manylinux glibc 2.28+ x86_64, ARM64

When a distribution reaches end-of-support, Package Manager will continue to serve existing binary packages for that system indefinitely. However, new binary packages will no longer be provided after a grace period of several months. For vendor end-of-support dates, see the Posit Platform Support page.

Note

The manylinux glibc 2.28+ distribution is based on RHEL 8 and shares the same end-of-support date as RHEL 8.

The following Linux distributions are no longer supported:

  • Ubuntu 20.04 (Focal)
  • Ubuntu 18.04 (Bionic)
  • Ubuntu 16.04 (Xenial)
  • CentOS 8
  • CentOS/RHEL 7
  • openSUSE 15.5, SLES 15 SP5
  • openSUSE 15.4, SLES 15 SP4
  • openSUSE 15.3, SLES 15 SP3
  • openSUSE 15.2, SLES 15 SP2
  • openSUSE 15.1, SLES 15 SP1
  • openSUSE 42.3, SLES 12 SP5
  • Debian 11 (Bullseye)

Supported R Versions

Package Manager provides binary packages for the current R version and the four previous minor versions. For example, if R 4.5 is the current version, binaries are available for R 4.5 (current), 4.4, 4.3, 4.2, and 4.1.

Binaries are built against the oldest compatible patch release within each minor version series. This ensures that binaries are compatible with any patch release in that series (e.g., binaries for R 4.5 will work with R 4.5.0 through R 4.5.X).

When an R version reaches end-of-support, Package Manager continues to serve existing binary packages for that version indefinitely, but stops providing new binaries after a grace period of several months.

Portable Linux Binary Packages

Package Manager supports a special type of Linux binary package known as “portable” binaries, available under the manylinux glibc 2.28+ distribution.

These binaries bundle their required system library dependencies within the package itself, so users do not need to install these libraries separately using a system package manager (such as apt or dnf). As a result, portable binaries are easier to install and work across a wide range of Linux distributions, rather than being specific to one.

This approach draws inspiration from widely used solutions in the Python packaging ecosystem, primarily the manylinux and auditwheel projects. These tools define a standard set of compatible system libraries to build packages against, and enable bundling those libraries directly within Python wheel files. Portable Linux binary packages leverage auditwheel to apply those same concepts to R packages.

The manylinux glibc 2.28+ binaries are built on RHEL 8 and compatible with any Linux distribution that uses glibc version 2.28 or newer. Alpine Linux and other distributions that use the musl libc library instead of glibc are not currently supported.

Why should I consider using them?

Portable Linux binary packages provide several advantages over traditional distribution-specific binary packages:

  • Improved user experience: Users no longer have to install runtime system library dependencies for R packages separately. Those working in shared environments with limited permissions no longer have to ask administrators to install system libraries just to use a new R package.
  • Improved admin experience: Administrators no longer have to track down and install system library dependencies manually.
  • Broad Linux support: Portable binary packages are compatible with more Linux distributions than Package Manager currently supports, such as Amazon Linux 2023.
  • Improved reproducibility: Packages use the system libraries available at runtime, which will change over time with system updates. Although Linux distributions are fairly stable, it is possible for a system library update or OS upgrade to potentially cause a failure or subtle differences in results, even if you haven’t updated your R package. Bundling specific versions of these libraries ensures long-term reproducibility.
  • Portability across R configurations: Portable binaries are designed to work with a wider range of R installations than the distribution-specific binaries, making them more broadly compatible with custom R installations.

Are these packages secure and safe to use?

Portable Linux binary packages are built using the same security practices as other Package Manager binaries. They are built in a secure environment, and the bundled libraries are regularly updated to include the latest security patches.

Because portable Linux binary packages bundle their own system libraries, they do not automatically receive security updates when the underlying system libraries are updated. Instead, users must reinstall the R package to receive the latest security updates.

This trade-off provides greater convenience and stability, but requires users to be proactive about reinstalling packages to stay secure.

Providing feedback

Portable Linux binary packages are currently available as a public preview. While these packages have been tested internally, you may encounter missing packages or compatibility issues during this phase.

If you experience any problems or have feedback, please share your thoughts on the Posit Community forum.

Binaries for Bioconductor Sources

At this time, Package Manager does not provide binary packages for Bioconductor sources. If you are interested in Bioconductor binary support, please share your feedback with Posit customer support (support@posit.co). All requests are collected for future consideration.

Binary Configuration Steps

By default, Package Manager serves binary packages for Windows, macOS, and Linux. Administrators can limit which distributions have binary support by setting the Binaries.Distributions configuration option.

Note

Limiting binary-enabled distributions also restricts which distributions you can upload your own binaries for in local and Git sources.

To enable binaries for specific distributions, provide a comma-separated list of distribution names:

/etc/rstudio-pm/rstudio-pm.gcfg
[Binaries]
; Enable binary packages for CentOS/RHEL 8, RHEL 9, Ubuntu 22.04 (Jammy), and Ubuntu 24.04 (Noble)
Distributions = "centos8, rhel9, jammy, noble"

To disable binary package support entirely, leave the value blank:

/etc/rstudio-pm/rstudio-pm.gcfg
[Binaries]
Distributions = ""

To see the list of available binary distributions, use the rspm list distributions command:

Terminal
$ rspm list distributions
Binary distributions:
  ...
  macos
  noble
  windows

Adding Local and Git Binaries

To add your own binary packages to local and Git sources, first add the source package to the source. Then, supplement it by adding binary packages for the desired R versions and distributions.

  1. For local sources, first build the source package using R CMD build. Then, add the source package to your local source with the rspm add command:

    Terminal
    R CMD build /path/to/package
# Produces package_1.0.0.tar.gz

rspm add --source=internal-src --path='/path/to/package_1.0.0.tar.gz'

    For Git sources, create a Git builder using the rspm create git-builder command. This will build the source package from your Git repository and add it to the source:

    Terminal
    rspm create git-builder --url=https://git.example.com/r-pkg.git --source=internal-src --build-trigger=tags

  2. Build the binary package using R CMD INSTALL --build on your target operating system, R version, and architecture. If the package does not contain compiled code, the resulting binary is architecture-independent and can be used across all architectures.

    Terminal
    # For Linux
R CMD INSTALL --build package_1.0.0.tar.gz
# Produces package_1.0.0_R_x86_64-pc-linux-gnu.tar.gz

# For Windows
R CMD INSTALL --build package_1.0.0.tar.gz
# Produces package_1.0.0.zip

# For macOS
R CMD INSTALL --build package_1.0.0.tar.gz
# Produces package_1.0.0.tgz

  3. Add the binary package to your source using the rspm add binary command. Be sure to specify the correct distribution, as binary packages do not indicate which Linux distribution was used to build the binary in their metadata. If you need to replace an existing binary, include the --replace flag.

    Terminal
    rspm add binary --source=internal-src --distribution=noble --path='/path/to/package_1.0.0_R_x86_64-pc-linux-gnu.tar.gz'
rspm add binary --source=internal-src --distribution=windows --path='/path/to/package_1.0.0.zip'
rspm add binary --source=internal-src --distribution=macos --path='/path/to/package_1.0.0.tgz'

    To see the list of supported distributions, run rspm list distributions:

    Terminal
    rspm list distributions
# Output includes: noble, windows, macos, etc.

For more examples of adding binary packages to local and Git sources, see:

Tip

When building R packages for Git sources, Package Manager automatically assigns a unique version to each source package based on the commit. The version includes a timestamp suffix, which can make it challenging to upload matching precompiled binary packages for the Git source.

To simplify uploading binary packages for Git sources, we recommend configuring the builder to use tags instead of commits. For more information, see the Commits vs Tags section.

If you need to upload binary packages for a Git source that uses a commit-based builder, you can use the Git.ForceDescriptionVersion configuration option to omit the timestamp from the version. This allows you to upload binary packages with a version that matches the source package version.

R Configuration Steps (Linux)

Prerequisites

To use Linux binary packages, an R user, Posit Workbench administrator, or Posit Connect 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:

  2. Identify the appropriate binary repository URL as described in Using Linux Binary Packages.

  3. If using the /__linux__/<distro> repository URLs, ensure that R includes the correct R version and architecture in its user agent header.

    For detailed steps, see Configuring the User Agent Header.

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

After configuring the environment, visit the repository Setup page in the web UI for instructions on setting up R, Posit Workbench, or Posit Connect to install Linux binary packages.

Package Manager supports two repository URL formats for Linux binary packages, each suited to different use cases:

  • /__linux__/<distro>
  • /bin/linux/<distro>-<arch>/<r-version>

The /__linux__/ URLs are distribution-specific and use the R client’s user agent header to determine the R version and architecture. These URLs work well in all environments, but may require additional steps to configure the R user agent correctly.

# Example binary repository URL for Ubuntu 24.04 (Noble)
https://packagemanager.example.com/cran/__linux__/noble/latest

The /bin/linux/ URLs specify the full package environment (distribution, architecture, and R version) in the URL, so they work without extra configuration. However, they may not be ideal for environments with multiple R versions, like Posit Workbench or Posit Connect.

# Example binary repository URL for Ubuntu 24.04 (Noble), x86_64, R 4.5
https://packagemanager.example.com/cran/latest/bin/linux/noble-x86_64/4.5

# Example binary repository URL for Ubuntu 24.04 (Noble), aarch64/arm64, R 4.5
https://packagemanager.example.com/cran/latest/bin/linux/noble-aarch64/4.5

When installing a package from a Linux binary repository 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 system, Package Manager falls back to serving the source version of the package.

You can determine whether Package Manager served a binary package by checking for this message in the R console when installing packages:

R
> install.packages("dplyr")
...
* installing *binary* package 'dplyr' ...

If the binary package was unavailable or unsupported, Package Manager will fall back to serving a source package:

R
> install.packages("dplyr")
...
* installing *source* package 'dplyr' ...
Note

When installing Linux binary packages with install.packages(), the type argument should be omitted. For example, use install.packages("dplyr") instead of install.packages("dplyr", type = "binary").

Configuring the R User Agent Header

When using /__linux__/<distro> repository URLs, R users and Posit Workbench admins may need to configure R to include the R version and architecture in the user agent for binary installation.

If you are using the /bin/linux/ repository URLs, you do not need to configure the user agent header. You can skip this step.

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:

R
# 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 user startup file (~/.Rprofile) or site-wide startup file (Rprofile.site), add:

%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 <- '# Configure the R user agent header to install Linux binary packages
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 == "curl") {
    if (!grepl(sprintf("User-Agent: %s", default_ua), dl_extra_args, fixed = TRUE)) {
      ua_arg <- "sprintf(\"-L --header 'User-Agent: R (%s)'\", paste(getRversion(), R.version[\"platform\"], R.version[\"arch\"], R.version[\"os\"]))"
      if (dl_extra_args != "") {
        old_args <- sprintf("\n  %s,", shQuote(dl_extra_args))
      } else {
        old_args <- ""
      }
      config <- paste0(
        'options(download.file.extra = paste(', old_args, '
  # Follow redirects, show errors, and display the HTTP status and URL
  "-fsSL -w \'%{stderr}curl: HTTP %{http_code} %{url_effective}\\n\'",
  # Configure the R user agent header to install Linux binary packages
  sprintf("--header \'User-Agent: R (%s)\'", paste(getRversion(), R.version["platform"], R.version["arch"], R.version["os"]))
))')
      message(sprintf(instruction_template, config))
      return(invisible())
    }
  } else if (dl_method == "wget") {
    if (!grepl(sprintf("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("# Configure the R user agent header to install Linux binary packages
options(download.file.extra = %s)", ua_arg)
      } else {
        config <- sprintf("# Configure the R user agent header to install Linux binary packages
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:

R
Success! Your user agent is correctly configured.

If this diagnostic fails, R should be configured to include the R version, architecture, and OS in the user agent header:

R
# Configure the R user agent header to install Linux binary packages
options(HTTPUserAgent = sprintf("R/%s R (%s)", getRversion(), paste(getRversion(), R.version["platform"], R.version["arch"], R.version["os"])))

If you have changed the download method in R to curl or wget, R should be configured to include the R version and operating system in the user agent header. For curl, the -L flag may also be required to follow redirects, if you have set Manifest.AllowRedirect to true.

Recommended download.file.extra options for curl and wget are shown below.

R
options(download.file.method = "curl")

options(download.file.extra = paste(
  # Follow redirects, show errors, and display the HTTP status and URL
  '-fsSL -w "%{stderr}curl: HTTP %{http_code} %{url_effective}\n"',
  # Configure the R user agent header to install Linux binary packages
  sprintf('--header "User-Agent: R (%s)"', paste(getRversion(), R.version["platform"], R.version["arch"], R.version["os"]))
))
R
options(download.file.method = "wget")

# Configure the R user agent header to install Linux binary packages
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 user startup file (~/.Rprofile) or site-wide startup file (Rprofile.site), so that R always starts with the correct configuration. See the article on managing R startup files for more information.

After configuring your user agent, you can rerun 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:

Terminal
$ curl -H "User-Agent: R (4.5.1 x86_64-pc-linux-gnu x86_64 linux-gnu)" -I https://packagemanager.example.com/cran/__linux__/noble/latest/src/contrib/dplyr_1.1.4.tar.gz
HTTP/1.1 200 OK
Content-Length: 87490
Content-Type: application/x-gzip
X-Package-Binary-Tag: 4.5-noble
X-Package-Type: binary

Or at an R console:

R
curlGetHeaders("https://packagemanager.example.com/cran/__linux__/noble/latest/src/contrib/dplyr_1.1.4.tar.gz")
# ...
# [10] "X-Package-Binary-Tag: 4.5-noble\r\n"
# [11] "X-Package-Type: binary\r\n"

R Configuration Steps (Windows and macOS)

Prerequisites

To use Windows or macOS 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, use the same repository URL as for source packages. For example, to install packages from the latest snapshot in a repository named cran, use:

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

When installing packages, R will display messages indicating whether a binary or source package was received from Package Manager.

If only the source package is available, you may see a message like this:

R
> install.packages('example-package', repos='https://packagemanager.example.com/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.

Package Manager aims to match CRAN’s compatibility requirements. For details, see CRAN’s documentation on installing R packages on Windows or installing R packages on macOS.

Back to top