usethis v1.5.1


Monthly downloads



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 Codecov test
coverage CRAN
status Lifecycle:

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 '/var/folders/yx/3p5dt4jj1019st0x90vhm9rr0000gn/T/RtmpWNMVxG/mypkg/'
#> ✔ Setting active project to '/private/var/folders/yx/3p5dt4jj1019st0x90vhm9rr0000gn/T/RtmpWNMVxG/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: What license it uses
#> Encoding: UTF-8
#> LazyData: true
#> ✔ Writing 'NAMESPACE'
#> ✔ Setting active project to '<no active project>'
# only needed since this session isn't interactive
#> ✔ Changing working directory to '/var/folders/yx/3p5dt4jj1019st0x90vhm9rr0000gn/T/RtmpWNMVxG/mypkg/'
#> ✔ Setting active project to '/private/var/folders/yx/3p5dt4jj1019st0x90vhm9rr0000gn/T/RtmpWNMVxG/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 various packages ---------------------------------------------
#> ✔ Setting Roxygen field in DESCRIPTION to 'list(markdown = TRUE)'
#> ✔ Setting RoxygenNote field in DESCRIPTION to '6.1.1'
#> ● Run `devtools::document()`

#> ✔ Creating 'src/'
#> ✔ Adding '*.o', '*.so', '*.dll' to 'src/.gitignore'
#> ● Copy and paste the following lines into '/private/var/folders/yx/3p5dt4jj1019st0x90vhm9rr0000gn/T/RtmpWNMVxG/mypkg/R/mypkg-package.R':
#>   ## usethis namespace: start
#>   #' @useDynLib mypkg, .registration = TRUE
#>   ## usethis namespace: end
#>   NULL
#> ✔ Adding 'Rcpp' to LinkingTo field in DESCRIPTION
#> ✔ Adding 'Rcpp' to Imports field in DESCRIPTION
#> ● Copy and paste the following lines into '/private/var/folders/yx/3p5dt4jj1019st0x90vhm9rr0000gn/T/RtmpWNMVxG/mypkg/R/mypkg-package.R':
#>   ## usethis namespace: start
#>   #' @importFrom Rcpp sourceCpp
#>   ## usethis namespace: end
#>   NULL

#> ✔ 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 ''

#> ✔ 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.
#> ✔ Increasing 'testthat' version to '>= 2.1.0' in DESCRIPTION
#> ✔ Writing 'tests/testthat/test-my-test.R'

x <- 1
y <- 2
use_data(x, y)
#> ✔ Creating 'data/'
#> ✔ Saving 'x', 'y' to 'data/x.rda', 'data/y.rda'

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

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.

Functions in usethis

Name Description
git_sitrep git/GitHub sitrep
use_build_ignore Add files to .Rbuildignore
use_github Connect a local repo with GitHub
use_citation Create a CITATION template
use_package_doc Package-level documentation
git_vaccinate Vaccinate your global git ignore
use_github_labels Manage GitHub issue labels
use_pipe Use magrittr's pipe in your package
tidyverse Helpers for tidyverse development
ui User interface
git_protocol Produce or register git protocol
usethis-package usethis: Automate Package and Project Setup
licenses License a package
use_cran_comments CRAN submission comments
use_coverage Test coverage
use_git_config Configure Git
use_description Create or modify a DESCRIPTION file
use_data Create package data
use_rstudio Add RStudio Project infrastructure
use_news_md Create a simple
use_package Depend on another package
proj_activate Activate a project
write-this Write into or over a file
pr_init Helpers for GitHub pull requests
proj_utils Utility functions for the active project
proj_sitrep Report working directory and usethis/RStudio project
use_git_hook Add a git hook
rprofile-helper Helpers to make useful changes to .Rprofile
use_pkgdown Use pkgdown
use_addin Add minimal RStudio Addin binding
use_rmarkdown_template Add an RMarkdown Template
zip-utils Download and unpack a ZIP file
use_r Create or edit a .R file
use_code_of_conduct Add a code of conduct
use_github_release Draft a GitHub release
use_roxygen_md Use roxygen with markdown
use_git Initialise a git repository
use_github_links Use GitHub links in URL and BugReports
use_course_details Helpers to download and unpack a ZIP file
use_directory Use a directory
use_spell_check Use spell check
use_vignette Create a vignette or article.
use_make Create Makefile
use_blank_slate Don't save/load user workspace between sessions
use_template Use a usethis-style template
use_git_ignore Tell git to ignore files
use_namespace Use a basic NAMESPACE
use_testthat Create tests
use_git_remote Configure and report Git remotes
usethis-defunct Defunct functions in usethis
use_jenkins Create Jenkinsfile for Jenkins CI Pipelines
use_release_issue Create a release issue checklist
use_tibble Prepare to return a tibble
use_tidy_thanks Identify contributors via GitHub activity
use_revdep Reverse dependency checks
use_rcpp Use C, C++, RcppArmadillo, or RcppEigen
use_tutorial Create a learnr tutorial
use_logo Use a package logo
use_readme_rmd Create README files
use_version Increment package version
browse-this Quickly browse to important package webpages
create_package Create a package or project
git_credentials Produce or register git credentials
edit_file Open file for editing
browse_github_token Create and retrieve a GitHub personal access token
badges README badges
edit Open configuration files
create_from_github Create a project from a GitHub repo
ci Continuous integration setup and badges
No Results!

Last month downloads


Include our badge in your README