Upgrading to a new version of R Last Updated: In other cases, R will find the existing packages, but they might not work correctly. The article of this document is to explain these problems, and how to fix them. On most single-user systems Mac, Windows, and Linux , when you upgrade to a new minor version of R like 3. This is an inconvenience, but the problem is obvious and it is easy to fix.
If you are using a system like this, you can just reinstall your packages after upgrading R. On servers running Linux, it is possible that after an R version upgrade, your R packages will load without trouble, but they might not work correctly, or they might even crash R when used.
Because the cause of these problems will not be obvious, upgrading R on a server should be done with care. In a production environment, we strongly suggest testing new versions of R and packages on a staging server before deploying to a production server. R version numbers have the form major. The current version as of the writing of this document, 3. New minor versions are released about once per year. In general, there are no issues with subminor version upgrades, like going from 3.
User libraries and version incompatibilities There are two possible sources of problems with R version upgrades, both of which are related to package libraries. A library is a directory where packages are stored. One problem is that, after upgrading to a new version of R, packages are no longer found because there is a new library. When this happens, the problem is obvious: The other problem that happens is more subtle.
Sometimes packages installed with a previous version of R will not work correctly with the new version of R. Sometimes they can crash the R process. And even when there is a crash, it will not be obvious that this it is because the package was installed with an old version of R.
In both cases, the solution is to reinstall packages with the new version of R. Detecting which version of R a package was built with The following code will show which packages are installed, their version numbers, and which version of R they were built with. The user is running R 3. In this particular case, the Cairo package was able to be loaded with library Cairo , but when functions from the package were called, it caused a segfault, crashing the R process. This is because it was built with an older version of R.
This issue most frequently happens on Linux, when root has installed some packages, though it can happen in other cases as well, if a customized configuration is used. Reinstalling packages with the new version of R After upgrading R, if you have any packages that were built with an older version of R, you should reinstall those packages to avoid compatibility issues.
There are two methods described below: For example, if you have Shiny version 1. The following code should be run as root after upgrading R on Linux. If this code is run as root after an R version upgrade, then users should not need to run this code unless they have their own copies of the same packages in their personal library. The first way is to use the base R function update. The pkgsnap package provides a way to reinstall packages without changing their version.
Install the pkgsnap package from GitHub source "https: Each platform Mac, Windows, and various flavors of Linux has a different default configuration, and therefore has different default behavior. This document will also explain the default settings for each platform, and what that means for dealing with R upgrade issues.
User and site libraries In all R installations, there is a site library: In some installations, there is more than one site library. Some R installations are also configured to have a user library: When a regular user starts R, it will recognize both the user library if configured for it and the site library.
If present, the user library is where packages will be installed to. If there is no user library, then packages will be installed to the site library, assuming the user has the correct permissions to do so. This is not how packages are usually installed, but it is sometimes done this way on servers. To find the libraries for your user, you can run. For example, this is what shows on Ubuntu Linux: Renviron in their home directory.
At a system level, the library path s can be set with an Renviron. See the R startup documentation page for more information. Versioned and unversioned libraries In some installations typically on Linux , R is configured to keep the same site library across R version upgrades. The problem here is that packages that built and installed with one version of R may be incompatible with a newer version of R, at least when the major or minor version changes.
Note that Subminor version upgrades of R generally do not introduce incompatibilities. In other installations typically on Mac and Windows , R is configured to use a new library when R has a major or minor version upgrade.
The drawback is that you must reinstall your packages after upgrading R. Customized library paths The user and site library paths can be customized. See the R startup documentation for more information. Platform-specific notes The default library configuration differs across platforms, and so the behavior after an R version upgrade also differs across platforms. Windows On Windows, the default user library has the major.
The default site library has the major. Only R version upgrades that involve a minor version change will result in the user library changing. When this happens, you will need to reinstall all your packages.
Upgrade is usually done explicitly by user. User library is versioned to minor. Site library is versioned to subminor. The site library has the major. Users on macOS usually have permission to write to the site library. R version upgrades that involve a minor version change will require the user to reinstall all packages. Does not have user library, so packages install to site library. Linux On Linux, the default user library has the major. The site library is not versioned.
There can be multiple site libraries, though this should not cause any differences in most use cases. On Mac and Windows, the user usually needs to go download the new version of R and install it, so it is obvious when R is upgraded. On Linux, R is usually upgraded in the process of a system software update, such as when you run apt-get upgrade on Debian or Ubuntu.
Additionally, Linux systems often have different people administering them and using them. For these two reasons, the installed version of R can change without the user being aware of it.
User-installed packages go into the user library. After R gets a minor version upgrade, the user will find that their user-installed packages are no longer available, and will need to reinstall all of them. This may come as a surprise to users, but the solution is straightforward. When Linux is being used on a server, there is another, more difficult scenario: When R is upgraded, those packages will continue to be available even after a major or minor version upgrade, but they potentially could be incompatible with the new version of R.
If this happens, users will experience problems like the ones described previously. In these cases, a user or system administrator should check which version of R each package was built with, and reinstall those packages that were built with an old version of R, as described above. One risk of doing this is that this will not only reinstall those R packages, but also upgrade the versions of those packages, which could cause problems if the newer version of the package has different behavior.
Because of these potential problems, administrators of Linux servers should be exercise caution when upgrading R. On most Linux distributions, it is possible to freeze system packages like R to a specific version, and only upgrade after testing.
Upgrade is usually something that happens with apt-get upgrade or yum update, and user might not be aware when it occurs. Site library is not versioned. If you have questions about this article or would like to discuss ideas presented here, please post on RStudio Community. Our developers monitor these forums and answer questions periodically.
See help for more help with all things Shiny.