Automate Package and Project Setup

Automate package and project setup tasks that are otherwise performed manually. This includes setting up unit testing, test coverage, continuous integration, Git, 'GitHub', licenses, 'Rcpp', 'RStudio' projects, and more.


Travis build status AppVeyor Build Status Coverage status CRAN status lifecycle

The goal of usethis is to automate many common package and analysis setup tasks.


Install the released version of usethis from CRAN:


Or install the development version from GitHub with:



Most use_*() functions operate on the current project. If you've just used usethis to create a new package or project, that will be the current project. Otherwise usethis tries to confirm that current working directory can be recognized as a project. Use proj_get() and proj_set() for manual intervention. Some functions have no strong connections to projects and will expect you to provide a path.

usethis is quite chatty, explaining what it's doing and assigning you tasks. indicates something usethis has done for you. indicates that you'll need to do some work yourself.

Below is a quick look at how usethis can help to set up a package.

Note: usethis is gaining more and more functionality for analytical project that are not packages. Stay tuned.

# Create a new package -------------------------------------------------
tmp <- file.path(tempdir(), "mypkg")
#> Changing active project to mypkg
#> ✔ Creating 'R/'
#> ✔ Creating 'man/'
#> ✔ Writing 'DESCRIPTION'
#> ✔ Writing 'NAMESPACE'
# Modify the description ----------------------------------------------
use_mit_license("My Name")
#> ✔ Setting License field in DESCRIPTION to 'MIT + file LICENSE'
#> ✔ Writing ''
#> ✔ Adding '^LICENSE\\.md$' to '.Rbuildignore'
#> ✔ Writing 'LICENSE'
use_package("MASS", "Suggests")
#> ✔ Adding 'MASS' to Suggests field in DESCRIPTION
#> ● Use `requireNamespace("MASS", quietly = TRUE)` to test if package is installed
#> ● Then use `MASS::fun()` to refer to functions.
#> ✔ Adding 'callr' to Imports field in DESCRIPTION
#> ● Refer to functions with `callr::fun()`
#> ✔ Adding 'r-lib/callr' to DESCRIPTION Remotes
# Set up various packages ---------------------------------------------
#> ✔ Setting Roxygen field in DESCRIPTION to 'list(markdown = TRUE)'
#> ✔ Setting RoxygenNote field in DESCRIPTION to ''
#> ● Re-document
#> ✔ Adding 'Rcpp' to LinkingTo field in DESCRIPTION
#> ✔ Adding 'Rcpp' to Imports field in DESCRIPTION
#> ✔ Creating 'src/'
#> ✔ Adding '*.o', '*.so', '*.dll' to 'src/.gitignore'
#> ● Include the following roxygen tags somewhere in your package
#>   #' @useDynLib mypkg, .registration = TRUE
#>   #' @importFrom Rcpp sourceCpp
#>   NULL
#> ● Run document()
#> ✔ Creating 'revdep/'
#> ✔ Adding '^revdep$' to '.Rbuildignore'
#> ✔ Adding 'checks', 'library', 'checks.noindex', 'library.noindex', 'data.sqlite', '*.html' to 'revdep/.gitignore'
#> ✔ Writing 'revdep/email.yml'
#> ● Run checks with `revdepcheck::revdep_check(num_workers = 4)`
# Set up other files -------------------------------------------------
#> ✔ Writing ''
#> ✔ Writing ''
#> ● Edit ''
#> ✔ Adding 'testthat' to Suggests field in DESCRIPTION
#> ✔ Creating 'tests/testthat/'
#> ✔ Writing 'tests/testthat.R'
#> ✔ Writing 'tests/testthat/test-my-test.R'
#> ● Edit 'tests/testthat/test-my-test.R'
x <- 1
y <- 2
use_data(x, y)
#> ✔ Creating 'data/'
#> ✔ Saving x to data/x.rda
#> ✔ Saving y to data/y.rda
# Use git ------------------------------------------------------------
#> ✔ Initialising Git repo
#> ✔ Adding '.Rhistory', '.RData', '.Rproj.user' to './.gitignore'
#> ✔ Adding files and committing


usethis 1.2.0

New functions

  • use_course() downloads a folder's worth of materials from a ZIP file, with deliberate choices around the default folder name and location. Developed for use at the start of a workshop. Helps participants obtain materials from, e.g., a DropBox folder or GitHub repo (#196).

  • use_blank_slate() provides a way to opt in to an RStudio workflow where the user's workspace is neither saved nor reloaded between R sessions. Automated for scope = "project". Provides UI instructions for scope = "user", for now (#139).

  • use_tidy_style() styles an entire project according to (#72, #197 @lorenzwalthert).

  • GitHub conventions common to tidyverse packages are enacted by use_tidy_contributing(), use_tidy_issue_template(), and use_tidy_support() (@batpigandme, #143, #166).

  • proj_path() forms paths relative to the current usethis project. Note: mostly useful internally. User code should probably use here or rprojroot directly (#149).

Other changes

  • New projects that don't exhibit other obvious criteria for being a "project" will include a sentinel, empty file named .here, so they can be recognized as a project.

  • Project launching and switching works on RStudio server (#115, #129).

  • use_template() is newly exported, so that other packages can provide templating functions using this framework (@ijlyttle #120).

  • use_readme_rmd() and use_readme_md() work, in a similar fashion, for projects that are and are not a package (#131, #135).

  • use_readme_rmd() once again creates a pre-commit git hook, to help keep README.Rmd and in sync (@PeteHaitch #41).

  • Substantial increase in unit test coverage.

usethis 1.1.0

New helpers

  • browse_github(), browse_github_issues(), browse_github_pulls(), browse_cran() and browse_travis() open useful websites related to the current project or a named package. (#96, #103).

  • create_from_github() creates a project from an existing GitHub repository, forking if needed (#109).

  • use_cc0_license() applies a CC0 license, particularly appropriate for data packages (#94)

  • use_lifecycle_badge() creates a badge describing current stage in project lifecycle (#48).

  • use_pkgdown() creates the basics needed for a pkgdown website (#88).

  • use_r("foo") creates and edit R/foo.R file. If you have a test file open, use_r() will open the corresponding .R file (#105).

  • use_tidy_versions() sets minimum version requirement for all dependencies.

Bug fixes and improvements

  • use_dev_version() now correctly updates the Version field in a package description file. (@tjmahr, #104)

  • use_revdep() now also git-ignores the SQLite database (#107).

  • use_tidy_eval() has been tweaked to reflect current guidance (#106)

usethis 1.0.0

This is a new package that extracts out many functions that previously lived in devtools, as well as providing more building blocks so you can create your own helpers. As well as the many new helpers listed below, there are three main improvements to the package:

  • More support for general R projects, other than packages.
  • A notion of an "active" project that all commands operate on.
  • Refined output.

usethis is gradually evolving towards supporting more general R "projects", not just packages. This is still a work in progress, so please let me know if you use a function that you think should work with projects but doesn't. You can also try out the new create_project() which creates a basic RStudio project.

The concept of the working directory and the "base path" have been refined. Rather than using an argument to specify the active project, all use_ functions now use a global active project setting, as returned by proj_get(). This is cached throughout a session, although it will be updated by create_package() and create_project(). You'll now get an clear error if you attempt to use_something() outside of a project, and create_something() will warn if you're trying to create inside an existing project.

The output from all usethis commands has been reviewed to be informative but not overwhelming. usethis takes advantage of colour (using crayon and RStudio 1.1) to help chunk the output and clearly differentiate what you need to do vs. what has been done for you.

New functions

  • use_apl2_license() if you want to use the Apache 2.0 license.

  • use_depsy_badge() allows including a Depsy badge (@gvegayon, #68).

  • use_dev_package() works like use_package() but also adds the repo to the Remotes field (#32).

  • use_github_labels() will automatically set up a standard set of labels, optionally removing the default labels (#1).

  • use_pipe() creates a template to use magrittr's %>% in your package (#15).

  • use_tidy_ci() which sets up travis and codecov using the tidyverse conventions (#14)

  • use_tidy_description() puts description fields in a standard order and alphabetises dependencies.

  • use_tidy_eval() imports and re-exports the recommend set of tidy eval helpers if your package uses tidy eval (#46).

  • use_usethis() opens your .Rprofile and gives you the code to copy and paste in.

New edit functions

A new class of functions make it easy to edit common config files:

  • edit_r_profile_user() opens .Rprofile
  • edit_r_environ_user() opens .Renviron
  • edit_r_makevars_user() opens .R/Makevars
  • edit_git_config_user() opens .gitconfig
  • edit_git_ignore_user() opens .gitignore
  • edit_rstudio_snippets(type) opens ~/R/snippets/{type}.snippets


  • use_coverage("codecov") now sets a default threshold of 1% to try and reduce false positives (#8).

  • use_description() now sets ByteCompile: true so you can benefit from the byte compiler (#29)

  • The license functions (use_mit_license(), use_apl2_license(), and use_gpl3_license()) save a copy of the standard license text in, which is then added to .Rbuildignore. This allows you to follow standard licensing best practices while adhering to CRANs requirements (#10).

  • use_package_doc() uses more modern roxygen2 template requires that less duplication.

  • use_test() will use the name of the currently open file in RStudio if you don't supply an explicit name (#89).

  • use_readme_rmd() now puts images in man/figures/ and no longer adds to .Rbuildgnore. This ensures that the rendered will also work on CRAN (#16, #19). The first chunk now uses include = FALSE and is named setup (#19).

  • use_revdep() creates structure for use with revdepcheck package, the preferred way to run revdepchecks. (#33)

Building blocks

  • New use_badge() for adding any badge to a README. Now only prints a todo message if the badge does not already exist.

  • use_directory() is now exported (#27).

Bug fixes and minor improvements

  • Functions which require code to be copied now automatically put the code on the clipboard if it is available (#52).

  • create_package() no longer creates a dependency on the current version of R.

  • use_build_ignore() now strips trailing /

  • use_git() will restart RStudio if needed (and possible) (#42).

  • use_github() now has an organisation parameter so you can create repos in organisations (#4).

  • use_template() and use_test() now convert title to a slug that only contains lowercase letters, numbers, and -.

  • use_vignette() now adds *.html and *.R to your .gitgnore so you don't accidentally add in compiled vignette products (#35).

Reference manual

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


1.3.0 by Hadley Wickham, 3 months ago

Report a bug at

Browse source code at

Authors: Hadley Wickham [aut, cre] (<>), Jennifer Bryan [aut] (<>), RStudio [cph, fnd]

Documentation:   PDF Manual  

GPL-3 license

Imports backports, clipr, clisymbols, crayon, curl, desc, gh, git2r, httr, rematch2, rmarkdown, rprojroot, rstudioapi, styler, whisker

Suggests covr, knitr, roxygen2, testthat, withr

Imported by codemetar, testthis, uCAREChemSuiteCLI.

Suggested by rstantools.

See at CRAN