R Package Management

Package installation

Posit Connect installs the R package dependencies of R-based content when that content is deployed. This includes Shiny applications, Plumber APIs, R Markdown documents, and Quarto projects that use R.

The RStudio IDE uses the rsconnect and renv R packages to identify the target source code and enumerate its dependencies. Source code is bundled into an archive (.tar.gz) file and uploaded to Posit Connect. In addition to the source, the bundle lists the requirements needed to run the content, such as the version of R and the versions of R packages used by the content.

When your content uses renv and an renv.lock is included in the deployment, the lock file is used to enumerate the required R package dependencies. When your content does not use renv or an renv.lock is not included in the deployment, the content is analyzed to discover what packages are needed; the version of each package is determined by inspecting your active R library.

Note

Prior to rsconnect-1.0.0, the packrat R package was used to analyze the content and discover its R package requirements. An renv.lock was ignored.

Posit Connect receives a bundle archive (.tar.gz) file, unpacks it, and uses packrat to install the identified package dependencies.

Note

Posit Connect includes and manages its own installation of the packrat package. This packrat installation is not available to user code and used only when restoring execution environments.

The execution environment created by Posit Connect and packrat contains the same package versions you are using in your development environment.

Note

Packrat uses the tar command to extract downloaded packages. Packrat determines the tar binary to use with the following heuristic:

  • If a TAR environment variable is set, respect that;
  • If on Unix, look for tar on the PATH;
  • If on Windows, look for the system tar and use that if it exists;
  • Otherwise, return use R’s internal tar implementation, which may encounter issues with long filenames.

Package caching

The packrat package attempts to re-use R packages whenever possible. The shiny package, for example, is installed when the first Shiny application is deployed. That version of shiny is placed into the package cache and associated with that Shiny application deployment. Other Shiny applications built with the same version of the shiny package will use that cached installation. Deployments are faster when they can take advantage of previously-installed packages.

The package cache allows multiple versions of a package to exist on a system. An old Shiny application built with shiny version 1.0.5 continues to use that package version even as newer deployments choose updated versions of shiny. Each Shiny application has an R environment with its expected shiny version. The different applications and shiny versions coexist.

Publish new content without worrying about package updates breaking existing, deployed content. Distinct versions of packages are kept isolated from each other.

Warning

In rare situations, systems maintenance requires you to clear the package caches. See the Runtime Caches section for details and instructions.

While environment caching is the default behavior in Posit Connect, there are alternative approaches that can be used to share packages across content items. These alternatives are useful in situations where the administrator needs more control over the packages used by the content at runtime, for example when packages are centrally managed (e.g., internal company packages).

The first option is to disable environment management entirely. By disabling environment management, the administrator declares that Connect should not perform any package installation. Only packages that are installed in the system-wide R library are available to the content at runtime. Alternatively, administrators can override specific packages by declaring the package as External in the Posit Connect configuration. This ensures that the system-wide version of that specific package is used when the content runs. Any packages not defined as external are still installed.

Package compilation

Some packages contain C and C++ code components. That code needs to be compiled during package installation. The Server.CompilationConcurrency setting controls the number of concurrent compilation processes used by package installation.

This property controls the number of concurrent C/C++ compilations during R package installation. High values may encounter memory capacity issues on lightweight hosts.

You can customize Server.CompilationConcurrency to force a specific level of concurrency.

; /etc/rstudio-connect/rstudio-connect.gcfg
[Server]
CompilationConcurrency = 1

R package repositories

R package repositories are servers from which R installs packages. In R, these are configured with a name and a URL (for example, CRAN mirrors are conventionally named CRAN). If R is configured to use multiple repositories and a package is available from more than one of those repositories, R obtains that package from the first repository from which it is available.

Some repositories (e.g. CRAN, Posit Package Manager) include a Repository field in the DESCRIPTION file for each package. The repository name from the package description is a well-known name for that repository (e.g. CRAN uses CRAN), but is not required to match the repository name given in R.

Posit Connect has two sources of R package repositories:

  • The Connect server configuration. One or more RPackageRepository sections can be used to define a set of repositories.
  • Published content. When content is deployed, the set of repositories used by the publishing computer are recorded and included in the content bundle sent to Connect.

See below for details on how Connect combines these sources of repository definitions, and how you can control this.

Configuring on publisher’s computers

On publishers’ computers, repository information is configured using the R repos option. Have your developers configure their R sessions to use your corporate repository.

Note

RStudio IDE version 0.99.1285 or greater is needed when using repositories other than the public CRAN mirrors.

We recommend using a $HOME/.Rprofile file on the deploying computer to configure multiple repositories or non-public repositories.

Note

The .Rprofile file should be created in a user’s home directory. Note that .Rprofile files in content directories will not be used during package installation on Posit Connect, even if they are included in deployed files.

# A sample .Rprofile file with two different package repositories.
options(repos = c(
  CRAN = "https://cran.rstudio.com/",
  mycompany = "http://rpackages.mycompany.com/"
))

This .Rprofile creates a custom repos option. It instructs R to attempt package installation first from "CRAN" and then from the "mycompany" repository. R installs a package from the first repository in "repos" containing that package.

This custom repos setting lets you install packages from your mycompany repository. Your configured repositories are captured when content is deployed to Posit Connect and used by Connect to install those same packages.

For more information about the .Rprofile file, see help(Startup) in R. For details about package installation, see help(install.packages) and help(available.packages).

Configuring on Posit Connect

Published content documents the R packages in use on the publisher’s computer. In its default configuration, Posit Connect will use those repositories to install R packages. If Connect has any repositories configured as RPackageRepository sections in its configuration, those will also be used. By default, both sets of repositories will be used, with configured repositories taking precedence.

You can control how Posit Connect combines repositories from its configuration and published content with the setting R.PackageRepositoryResolution:

  • lax (default): Append repositories defined by content to the list of RPackageRepository definitions, using the combined list as the set of available repositories. Repository names are made unique as necessary. Duplicate URLs are not added to the list; Posit Package Manager URLs are rewritten before merging.
  • strict: Use only configured RPackageRepository entries, discarding repositories used by the publishing computer.
  • legacy: Start with the list of repositories from the content. If any names from configured RPackageRepository entries match, override the incoming URL with the configured URL.
Note

The legacy behavior was the only behavior available before Posit Connect version 2023.08.0.

Example: lax

By default, or when R.PackageRepositoryResolution is set to lax, both configured RPackageRepository entries and repositories used on the publisher’s computer are available for package install. This setting allows for successful restores in most situations.

; /etc/rstudio-connect/rstudio-connect.gcfg
[R]
PackageRepositoryResolution = lax

[RPackageRepository "CRAN"]
URL = https://packagemanager.company.com/cran/latest

If published content uses repositories that are not configured on Connect, those repositories are available for package install. In the example below, the name CRAN refers to a different URL than the Connect instance, and the name RSPM is used to refer to the same URL that is configured on Connect.

options(
  repos = c(
    CRAN = "https://cran.rstudio.com/",
    RSPM = "https://packagemanager.company.com/cran/latest"
  )
)

The final set of repositories available for package installation includes Connect’s configured repository first, and also includes any unique URLs in the content’s repository list.

options(
  repos = c(
    CRAN = "https://packagemanager.company.com/cran/latest",
    CRAN.1 = "https://cran.rstudio.com/"
  )
)

Example: strict

When R.PackageRepositoryResolution is set to strict, only configured RPackageRepository entries are used for package restore. You can configure multiple of RPackageRepository entries.

For example, if your company has configured an approved subset of packages in a Posit Package Manager instance, and wants to prohibit the publication of content using unapproved packages. You can configure the following:

; /etc/rstudio-connect/rstudio-connect.gcfg
[R]
PackageRepositoryResolution = strict

[RPackageRepository "CRAN"]
URL = https://packagemanager.company.com/cran-approved/latest

When content is published, configured RPackageRepository entries are available, no matter what repositories were used on the publisher’s computer.

options(
  repos = c(
    CRAN = "https://packagemanager.company.com/cran-approved/latest"
  )
)

All content environments are constructed from these packages. Content that uses packages that are not available in this repository will fail to deploy.

Note

When setting R.PackageRepositoryResolution is set to strict, Connect will fail to start if no RPackageRepository is configured.

Example: legacy

When R.PackageRepositoryResolution is set to legacy, Connect uses configured RPackageRepository entries to override the URLs of repositories in published content, matched by name.

For example, the following configuration would override all repositories named CRAN with a URL that installs binary R packages from Posit Package Manager.

; /etc/rstudio-connect/rstudio-connect.gcfg
[R]
PackageRepositoryResolution = legacy

[RPackageRepository "CRAN"]
URL = https://packagemanager.company.com/cran/__linux__/jammy/latest

The RPackageRepository name must exactly match the name your developers use when configuring options("repos") in R. An RPackageRepository definition is used only when a particular piece of content references that repository name.

We recommend using the R.PositPackageManagerURLRewriting setting to automatically install binary packages from Posit Package Manager, rather than manually setting up repository override URLs in this manner.

Posit Package Manager URL rewriting

Posit Package Manager can serve R packages as source or precompiled binaries. Precompiled binaries install much faster, but are only compatible with the Linux distribution for which they were compiled. For more detail, see Posit Package Manager documentation on Binary Packages and Using Linux Binary Packages.

Note

Package Manager URL rewriting only applies to Posit Package Manager URLs. Other R package repositories (e.g. vanilla CRAN mirrors, Bioconductor, Artifactory, or filesystem repositories) are not affected.

The type of package served by Posit Package Manager is determined by the URL. For instance, https://packagemanager.posit.co/cran/latest serves source packages, while https://packagemanager.posit.co/cran/__linux__/jammy/latest serves binary packages for Ubuntu 22.04.

Use the setting R.PositPackageManagerURLRewriting to control how Connect downloads packages from a Posit Package Manager instance. This setting affects both repositories configured on Connect using RPackageRepository, and arbitrary repository URLs in published content.

The R.PositPackageManagerURLRewriting setting takes one of four values:

  • auto (default): Incompatible Posit Package Manager binary URLs will be rewritten to use compatible binaries, if they are served by the Package Manager instance. Otherwise, they will be rewritten to use source packages. Source package URLs, compatible binary URLs, and other repository URLs are unmodified.
  • force-source: All Posit Package Manager URLs are rewritten to use source packages.
  • force-binary: All Posit Package Manager URLs are rewritten to use binary packages, assuming they are served by the Package Manager instance. Otherwise, they are rewritten to use source packages.
  • none: Disables all rewriting of Posit Package Manager URLs. Use of this value is not recommended.

Example

With the default behavior (R.PositPackageManagerURLRewriting = auto), Posit Connect rewrites incompatible Posit Package Manager binary URLs and leaves all other URLs unmodified. For example, on Ubuntu 22.04 (Jammy):

  • https://packagemanager.posit.co/cran/latest is unmodified, because it installs source packages.
  • https://packagemanager.posit.co/cran/__linux__/jammy/latest is unmodified, because it installs compatible binary packages.
  • https://packagemanager.posit.co/cran/__linux__/focal/latest is rewritten to https://packagemanager.posit.co/cran/__linux__/jammy/latest, because it installs binary packages compiled for a different version of Ubuntu.

To rewrite all URLs to install source packages, use:

; /etc/rstudio-connect/rstudio-connect.gcfg
[R]
PositPackageManagerURLRewriting = force-source

To rewrite all URLs to install compatible binaries:

; /etc/rstudio-connect/rstudio-connect.gcfg
[R]
PositPackageManagerURLRewriting = force-binary

External package installation

Warning

Adding external packages decreases the reproducibility and isolation of content on Posit Connect, and should only be done as a last resort. To use private packages with Posit Connect, see the section on Private Packages below.

Configuring external packages is an advanced configuration option. If possible, users should prefer using the R environment management settings for their content.

You can indicate that certain R packages should not be installed and managed by Connect and packrat. These packages must be contained in the R library for each installed version of R. Use the R.External setting to enumerate R packages that should not be managed by Connect.

For example, rJava or ROracle are large installations, potentially with complex, external dependencies, such as your choice of JDK and/or Oracle InstantClient. Install these packages into every R installation used by Posit Connect, then configure Connect to treat those packages as external:

; /etc/rstudio-connect/rstudio-connect.gcfg
[R]
External = ROracle
External = rJava

Posit Connect will report an error during startup if some of the external R packages are missing from any configured R installation. If you are not able to install an external R package into all R installations (perhaps because that package is not compatible with some versions of R), use the R.ExternalsCheckIsFatal setting to prevent this check.

; /etc/rstudio-connect/rstudio-connect.gcfg
[R]
ExternalsCheckIsFatal = false
Note

The R.External setting uses the packrat option external.packages to indicate that certain packages are outside the project. The packrat documentation explains external.packages and its use by packrat::restore().

Proxy configuration

If the http_proxy and/or https_proxy environment variables are provided to Posit Connect when the server starts, those variables will be passed to all processes run by Posit Connect, including the package installation process.

Configuring Packages.HTTPProxy and Packages.HTTPSProxy will provide their values as the http_proxy and https_proxy environment variables only when packages are installed during deployment. This could be useful if you have a special proxy just for downloading package dependencies. You could regulate access to unapproved packages in non-CRAN repositories by rejecting certain URL patterns.

Environment management

By default, Posit Connect is responsible for managing the R environment that is required by the bundle at runtime. Connect manages the environment by installing the required packages with packrat during a content deployment. The R environment is then made available at runtime during content execution. The R environment management behavior can be controlled by either an administrator, or the content owner. When environment management is disabled, it is the responsibility of the administrator to ensure that the packages required by the content bundle are available in the runtime environment.

With local execution, the R packages must be installed in the system R library for the version of R that is requested by the content. When off-host execution is enabled, the R packages must be installed in the R library in the image that is used to execute the content. The selected R installation (and image name) can be found on the dashboard Info tab in the Application Settings pane.

There are 3 ways to configure the R environment management strategy. From lowest to highest precedence:

  1. Server administrators can configure a global environment management strategy at the server-level with the R.EnvironmentManagement setting (default true).

  2. Administrators and content owners can configure an application-level R environment management strategy. If set, this option is used, and the global server setting is ignored. Users can set an application-level default with the Server API or by selecting the R environment management strategy in the Runtime tab on the Content Settings panel in the Connect dashboard.

  3. Publishers can configure a bundle-level environment management strategy. If set, this option is always used, and the application-level default and the global server-level default settings are ignored. To set a bundle-level environment management strategy, users can set the environment.environment_management.r field in the bundle manifest.json. The rsconnect (1.1.0+) R package supports an env_management_r argument so that users can specify an R environment management strategy when deploying content.

Note

Push-button deployment from the IDE does not currently support selecting an environment management strategy.

Private R packages

Most R packages in R projects are installed from public CRAN mirrors, but Posit Connect supports multiple ways of using private R packages in deployed content.

From private R package repositories

Most public packages will come from a public CRAN mirror, but Posit Connect supports installing packages from alternate repositories, which can be used to host private packages.

Note

Private R package repositories can be served using software like Posit Package Manager. You can also create your own custom repository in a directory, which can then be shared over HTTP or through a shared filesystem.

Here are some reasons why your organization might use an alternate/private repository.

  1. Internally developed packages are made available through a corporate repository. This is used in combination with a public CRAN mirror.

  2. All packages (private and public) are approved before use and must be obtained through the corporate repository. Public CRAN mirrors are not used.

  3. Direct access to a public CRAN mirror is not permitted. A corporate repository is used as a proxy and caches public packages to avoid external network access.

By default, Posit Connect will use the repositories used by the computer deploying the content. If Connect can use those servers, no further configuration is needed.

Alternatively, you can use define a set of repositories for Connect to use use either alongside (with a higher priority) or instead of repositories from published content. Define R package repositories using the RPackageRepository option. See above for information on controlling the set of repositories used for package installation.

From private Git repositories

Posit Connect and packrat can use the Git credentials from the Connect configuration to download R packages from private Git repositories that are hosted on GitHub, GitLab, and Bitbucket.

Note

Note that packrat does not support instances of these Git providers hosted at URLs other than github.com, gitlab.com, and bitbucket.com.

Warning

When this setting is enabled, all package downloads from GitHub, GitLab, and Bitbucket will include the credentials. If credentials are invalid, all package installations, including those from public repos, will fail.

To allow Connect to use configured Git credentials for package restore, set the R.RestoreUsesGitCredentials setting to true.

; /etc/rstudio-connect/rstudio-connect.gcfg
[R]
RestoreUsesGitCredentials = true

You must also configure Git credentials as you would to deploy content from private Git repositories. See the section on Git-backed content and refer to GitCredential in the Configuration appendix for more information. The account you configure must be able to access any Git repositories containing R packages you wish to use.

Publishers must also configure appropriate Git provider credentials on their computer. They then install the package locally using an R package like remotes. For instance, to install a package from GitHub:

remotes::install_github("mycompany/mypackage")

When deploying content that uses this package, details about the GitHub package location are included. Posit Connect will obtain the same version of the package from GitHub when building an environment for your content.