Upgrading Packages
How to Safely Upgrade Packages
Upgrading packages can be a risky affair. Most R users have been in a situation where upgrading a package had unintended consequences. For example, the upgrade broke part of their code, or upgrading a package for one project accidentally broke the code in another project. Luckily, the strategies for reproducible environments can make package upgrades safe.
Specifically, there are two ways reproducible environments support package upgrades:
- They encourage project isolation.
- They provide a safety net in case you need to roll back a change.
This page describes the Snapshot and Restore strategy with an emphasis on package upgrades. Keep in mind that the other strategies promote safe package upgrades as well. We also present troubleshooting tips for cases where upgrading a package breaks code.
Snapshot and Restore for Upgrades
The first concern for safe upgrades is project isolation. By isolating projects, you can ensure that upgrading the packages for one project won’t break code in other projects. This type of isolation is accomplished by creating per-project libraries. The renv package makes this easy. Inside of your R project, simply use:
# inside the project directory
renv::init()
# check to see the isolated project library
.libPaths()The next concern for safely upgrading packages is creating a safety net. If the package upgrade goes poorly, you’ll be able to revert the changes and return to a working state. Again, the renv package makes this process easy.
# record the current dependencies in a file called renv.lock
renv::snapshot()
# commit the lockfile alongside your code in version controlWith an isolated project and a safety net in place, you can now proceed to upgrade or add new packages, while remaining certain the current functional environment is still reproducible. The pak package can be used to install and upgrade packages in an interactive environment:
# upgrade packages quickly and safely
pak::pkg_install("ggplot2")
# the interactive prompt shows you exactly what will change
# helping avoid unintentional or surprising changesIf the process of upgrading packages goes poorly, you can roll back the change using the safety net created earlier:
# use this function to view the history of your lockfile
renv::history()
# if an upgrade goes astray, revert the lockfile
renv::revert(commit = "abc123")
# and restore the previous environment
renv::restore()The safety net provided by the renv package relies on access to older versions of R packages. For public packages, CRAN provides these older versions in the CRAN archive. Organizations can use tools like Package Manager to make multiple versions of private packages available.
What if an upgrade breaks code?
A common problem after upgrading packages is to hit an error running the library statements in your code. This occurs because package upgrades can leave your project library in an inconsistent state. One fix is to upgrade all of the packages used in your project. It is best to restart the R session prior to performing these upgrades, as loaded packages can often prevent successful upgrades. The Validated and Shared Baseline strategies address this problem by requiring upgrades to the entire repository.
If all of your library statements work, but your code still fails to run, it is likely the functions in a package changed. At this point you can roll back your change or take time to investigate and update your code. The first place to look is the package’s News file. For example, this is the ggplot2 News file. A News file will what has changed, and detail what steps a user will should take in order to adapt their code. Focus on the changes listed between the version you were using and latest version - both pieces of information are displayed in the pak install prompt. Normally you can identify the problematic package based on where the error occurs in your code. The itdepends package can also help you identify which functions are in use.