Skip to content
Set up commonly used πŸ“¦ components
R Makefile Shell Groovy Rebol C
Branch: master
Clone or download


R build status Codecov test coverage CRAN status Lifecycle: stable

usethis is a workflow package: it automates repetitive tasks that arise during project setup and development, both for R packages and non-package projects.


Install the released version of usethis from CRAN:


Or install the development version from GitHub with:

# install.packages("devtools")


Most use_*() functions operate on the active project: literally, a directory on your computer. If you’ve just used usethis to create a new package or project, that will be the active project. Otherwise, usethis verifies that current working directory is or is below a valid project directory and that becomes the active project. Use proj_get() or proj_sitrep() to manually query the project and read more in the docs.

A few usethis 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. But remember, many usethis functions are also applicable to analytical projects that are not packages.


# Create a new package -------------------------------------------------
path <- file.path(tempdir(), "mypkg")
#> βœ“ Creating '/tmp/RtmppskQJj/mypkg/'
#> βœ“ Setting active project to '/private/tmp/RtmppskQJj/mypkg'
#> βœ“ Creating 'R/'
#> βœ“ Writing 'DESCRIPTION'
#> Package: mypkg
#> Title: What the Package Does (One Line, Title Case)
#> Version:
#> Authors@R (parsed):
#>     * First Last <> [aut, cre] (<>)
#> Description: What the package does (one paragraph).
#> License: `use_mit_license()`, `use_gpl3_license()` or friends to pick a
#>     license
#> Encoding: UTF-8
#> LazyData: true
#> Roxygen: list(markdown = TRUE)
#> RoxygenNote: 7.1.0
#> βœ“ Writing 'NAMESPACE'
#> βœ“ Setting active project to '<no active project>'
# only needed since this session isn't interactive
#> βœ“ Changing working directory to '/tmp/RtmppskQJj/mypkg/'
#> βœ“ Setting active project to '/private/tmp/RtmppskQJj/mypkg'

# 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 directly refer to functons like `MASS::fun()` (replacing `fun()`).

# Set up other files -------------------------------------------------
#> βœ“ Writing ''

#> βœ“ Writing ''

#> βœ“ Adding 'testthat' to Suggests field in DESCRIPTION
#> βœ“ Creating 'tests/testthat/'
#> βœ“ Writing 'tests/testthat.R'
#> ● Call `use_test()` to initialize a basic test file and open it for editing.
#> βœ“ Writing 'tests/testthat/test-my-test.R'
#> ● Edit 'tests/testthat/test-my-test.R'

x <- 1
y <- 2
use_data(x, y)
#> βœ“ Adding 'R' to Depends field in DESCRIPTION
#> βœ“ Creating 'data/'
#> βœ“ Saving 'x', 'y' to 'data/x.rda', 'data/y.rda'
#> ● Document your data (see '')

# Use git ------------------------------------------------------------
#> βœ“ Initialising Git repo
#> βœ“ Adding '.Rhistory', '.RData', '.Rproj.user' to '.gitignore'

Code of Conduct

Please note that the usethis project is released with a Contributor Code of Conduct. By contributing to this project, you agree to abide by its terms.

You can’t perform that action at this time.