Upgrading 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 control
With 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 changes
If 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 RStudio 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.