R Package Management on Posit Workbench – Posit Support

The way you manage R packages and R package installations on your Workbench host is crucial, especially when developing your workflows, and navigating your local Linux servers' technical requirements. This article will walk through the basics of package installation within R.

R Package Installation Basics

To install a package in R, the install.packages() function is typically used. For example:

install.packages("ggplot2")

This command downloads and installs the package from a CRAN mirror to a specific library directory. By default, R installs packages into the library directory defined by the lib.loc argument of install.packages(). If no location is specified, R will use a default path.

Default Library Locations and User Libraries

The default library path for R packages depends on the user’s setup and the version of R being used. The library locations can be classified into two types: system libraries and user libraries.

System Libraries

System libraries are directories where R packages are installed for all users on the server. These directories are usually managed by the systems administrator, and users will not have write permissions to them. When installing packages into the system library, administrative privileges (root access) is required. On most Linux systems, the system-wide library directories are located in:

/usr/lib/R/library/
/usr/local/lib/R/site-library/

User Libraries

User libraries are directories specific to an individual user. These libraries are created in the user home directory and do not require administrative privileges to modify. When installing packages into the user library, R defaults to the user’s home directory, specifically:

~/.local/lib/R/site-library/

When R starts, the user library is included in the search path, allowing R to access installed packages. The advantage of user libraries is that users can install and manage their own packages without affecting other users on the system.

Default Behavior for Different Users

System-Wide Installation (Admin user)

If you're an administrator using sudo privileges, R installs packages in system libraries (for example /usr/lib/R/library/). These libraries are available to all users on the system but require elevated permissions for modification. This is the default installation behavior when no custom library path is specified, and the user has root access.
Default Installation for Regular Users

If you're a non-administrative user (without root access), R will install packages into a user-specific library (such as ~/.local/lib/R/site-library/). You can check the current library paths by running the following in R:
```
.libPaths()
```
This will return a vector of library directories, with the first entry typically being the user-specific library path.
Custom Installation Path

Users can override the default installation path by setting the lib argument in the install.packages() function. For example:
```
install.packages("dplyr", lib = "/path/to/custom/library")
```
This will install the package into the specified directory, provided that the user has write permissions to the directory specified.

Working with Package Dependencies

R Package Dependencies

When installing a package, R often needs to install additional packages that the primary package depends on. R will automatically attempt to resolve and install these dependencies from CRAN or other repositories (if you have these specified). However, this can sometimes cause issues, especially when system-wide dependencies or system libraries are required. In such cases:

Package Dependencies in User Libraries: When a non-root user installs packages, R installs dependencies into the user's library directory. However, if a required dependency is not available or requires system libraries, the installation might fail unless those system libraries are installed by the administrator.

Package Dependencies in System Libraries: If you have administrative privileges, R will install both the main package and its dependencies into the system library directory, making it available to all users.

System dependencies

While R packages can be self-contained, many require system dependencies to be installed on your Linux server. These dependencies typically consist of libraries and tools that are not directly part of R but are required for certain R packages to function properly. These can include, for example, C libraries, compilation tools, and external programs. When installing a package that has system dependencies that have not been met, you will see an error similar to the below:

----------------------------- ANTICONF -------------------------------
Configuration failed to find <package> library. Try installing:
* brew: <Linux package> (MacOS)
* deb: <Linux package> (Debian, Ubuntu, etc)
* rpm: <Linux package> (Fedora, CentOS, RHEL)
If <Linux package> is already installed, check that 'pkg-config' is in your
PATH and PKG_CONFIG_PATH contains a <Linux package>.pc file. If pkg-config
is unavailable you can set INCLUDE_DIR and LIB_DIR manually via:
R CMD INSTALL --configure-vars='INCLUDE_DIR=... LIB_DIR=...'

This occurs when a system-level package is not installed. There may be instances where the package is installed, but has not been added to the PATH. However, in most cases, this is due to the package not being installed on the server. The fix here, is to manually install the system package using the package manager of your operating system.

Source vs Binary Packages

Source Packages

A source package contains the original code of the package. They take the form of .tar.gz (in most cases), and when installed, R will need to compile the code to create a working version of the package to use in your R environment. Source packages are portable because they can be used on any OS, so long as the OS has the necessary system dependencies to build these packages. Source packages also use the most up-to-date version of the package also.

Binary Packages

A binary package is a pre-compiled version of a package that has been built for a specific OS. Instead of R needing to compile the code, a binary package is the ready-to-use version of the R package. Binary packages are much easier and faster to install because the code has already been compiled. These pre-compiled binary packages are in .zip/.tgz format. They are, however, specific to an operating system and architecture (32 vs 64 bit) so they won't work on all platforms. You will need to use the specific binary for your operating system. Binary packages typically are not the latest version of a package, as they need to be built for a specific OS. If possible, it's recommended to use binary packages. Most binary packages that are available only exist for Windows and MacOS. However, Posit Package Manager allows for binary packages in Linux:

https://docs.posit.co/rspm/admin/getting-started/installation/

Best Practices

The best practice recommendation is to use binary packages for package installation. It's also highly recommended to adjust the permissions on your site and user libraries conforming to the principle of least privilege.

pak and renv

Managing R packages in multi-user and multi-project environments can become difficult as the use of R grows. As such, it's important to ensure that R packages and their dependencies are isolated and reproducible. Tools like renv and pak can make this administration easier.

renv is an R package designed to help users manage project-specific package libraries, and ensures that all dependencies are isolated from the global system library. It contains a virtualized R environment for each R project, allowing you to specify and lock specific versions of R packages to ensure that the same versions of packages are used every time the project is loaded. Our renv documentation can be found below:

https://docs.posit.co/ide/user/ide/guide/environments/r/renv.html

pak is an R package designed to improve the management of package installation. It works as a replacement for the install.packages() function. Pak is a replacement for the install.packages() function and can be used in addition to renv. The pak documentation can be found below:
https://pak.r-lib.org/