Run Code 'With' Temporarily Modified Global State

A set of functions to run code 'with' safely and temporarily modified global state. Many of these functions were originally a part of the 'devtools' package, this provides a simple package with limited dependencies to provide access to these functions.

Travis-CI BuildStatus AppVeyor BuildStatus Coveragestatus CRANVersion

A set of functions to run code ‘with’ safely and temporarily modified global state. There are two sets of functions, those prefixed with with_ and those with local_. The former reset their state as soon as the code argument has been evaluated. The latter reset when they reach the end of their scope, usually at the end of a function body.

Many of these functions were originally a part of the devtools package, this provides a simple package with limited dependencies to provide access to these functions.

  • with_collate() / local_collate() - collation order
  • with_dir() / local_dir() - working directory
  • with_envvar() / local_envvar() - environment variables
  • with_libpaths() / local_libpaths() - library paths
  • with_locale() / local_locale() - any locale setting
  • with_makevars() / local_makevars() - Makevars variables
  • with_options() / local_options() - options
  • with_par() / local_par() - graphics parameters
  • with_path() / local_path() - PATH environment variable
  • with_*() and local_() functions for the built in R devices, bmp, cairo_pdf, cairo_ps, pdf, postscript, svg, tiff, xfig, png, jpeg.
  • with_connection() / local_connection() - R connections.
  • with_package(), with_namespace() and with_environment() - to run code with modified object search paths.
  • with_tempfile() / local_tempfile() - Create and clean up a temp file.
  • with_file() / local_file() - Create and clean up a normal file.

There are also with_() and local_() functions to construct new with_* and local_* functions if needed.

#> [1] ""
with_envvar(c("WITHR" = 2), Sys.getenv("WITHR"))
#> [1] "2"
#> [1] ""
with_envvar(c("A" = 1),
  with_envvar(c("A" = 2), action = "suffix", Sys.getenv("A"))
#> [1] "1 2"

local functions

These functions are variants of the corresponding with_() function, but rather than resetting the value at the end of the function call they reset when the current context goes out of scope. This is most useful for using within functions.

f <- function(x) {
  local_envvar(c("WITHR" = 2))
#> [1] ""

See Also


withr 2.1.2

  • set_makevars() is now exported (#68, @gaborcsardi).

  • with_temp_libpaths() gains an action argument, to specify how the temporary library path will be added (#66, @krlmlr).

withr 2.1.1

  • Fixes test failures with testthat 2.0.0

  • with_file() function to automatically remove files.

withr 2.1.0

  • with_connection() function to automatically close R file connections.

  • with_db_connection() function to automatically disconnect from DBI database connections.

  • with_gctorture2 command to run code with gctorture2, useful for testing (#47).

  • with_package(), with_namespace() and with_environment() (and equivalent locals) functions added, to run code with a modified object search path (#38, #48).

  • Add with_tempfile() and local_tempfile() functions to create temporary files which are cleanup up afterwards. (#32)

  • Remove the code argument from local_ functions (#50).

withr 2.0.0

  • Each with_ function now has a local_ variant, which reset at the end of their local scope, generally at the end of the function body.

  • New functions with_seed() and with_preserve_seed() for running code with a given random seed (#45, @krlmlr).

withr 1.0.2

  • with_makevars() gains an assignment argument to allow specifying additional assignment types.

withr 1.0.1

  • Relaxed R version requirement to 3.0.2 (#35, #39).
  • New with_output_sink() and with_message_sink() (#24).

withr 1.0.0

  • First Public Release

Reference manual

It appears you don't have a PDF plugin for this browser. You can click here to download the reference manual.


2.1.2 by Jim Hester, a year ago,

Report a bug at

Browse source code at

Authors: Jim Hester [aut, cre] , Kirill Müller [aut] , Kevin Ushey [aut] , Hadley Wickham [aut] , Winston Chang [aut] , Richard Cotton [ctb] , RStudio [cph]

Documentation:   PDF Manual  

GPL (>= 2) license

Imports stats, graphics, grDevices

Suggests testthat, covr, lattice, DBI, RSQLite, methods, knitr, rmarkdown

Imported by DBItest, FSA, IOHanalyzer, RFishBC, RPostgres, anyLib, batchtools, caret, cliapp, cloudml, covr, cyclocomp, detrendr, devtools, dials, document, fakemake, fgeo.analyze, filesstrings, flippant, gargle, gdtools, ggplot2, ggridges, ggstance, goodpractice, ijtiff, learnr, mlflow, mudata2, nandb, pkgbuild, pkgcache, pkgdown, pkgload, pkgmaker, prettycode, prodigenr, profile, raws.profile, rcmdcheck, recipes, reprex, rhub, roxygen2md, sessioninfo, shinytest, sparklyr, styler, tatoo, testthat, usethis, vroom, webdriver.

Suggested by BiocManager, EdSurvey, IRdisplay, bench, bigrquery, callr, cli, cranlike, crayon, crunch, crunchy, datarobot, dbplyr, debugme, desc, dplyr, enc, encryptr, exuber, fs, fy, ggExtra, ggspatial, ggthemes, glue, grattan, hutils, irace, jetpack, jwutil, keyring, knitrProgressBar, liteq, miniCRAN, pak, parsedate, pathological, pillar, pkgnet, processx, progress, rasciidoc, rdoc, remotes, rosm, rotor, rprojroot, secret, skimr, stevedore, surveydata, testextra, tibble, tikzDevice, vaultr, vdiffr, whoami, workflowr, zip.

See at CRAN