usethis v1.2.0


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 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:

# install.packages("devtools")


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

Functions in usethis

Name Description
proj_get Get and set currently active project
tidyverse Helpers for the tidyverse
use_badge Use a README badge
use_blank_slate Don't save/load user workspace between sessions
use_cran_badge Create a CRAN badge
use_cran_comments CRAN submission comments
use_course Download course materials
use_course_details Download and unpack a ZIP file
use_directory Use a directory.
use_git Initialise a git repository.
use_template Use a usethis-style template
use_testthat Create tests
edit Open useful configuration files
licenses Use MIT, GPL-3, or Apache 2.0 license for your package
use_description Create a default DESCRIPTION file for a package.
use_dev_version Increment to a development version
use_lifecycle_badge Create a life cycle badge
use_namespace Use a basic NAMESPACE
use_roxygen_md Use roxygen with markdown
use_rstudio Use RStudio
use_data Create package data
use_depsy_badge Create a Depsy badge
use_git_hook Add a git hook.
use_git_ignore Tell git to ignore files
use_package_doc Package-level documentation
use_pkgdown Use pkgdown
use_r Create a new R file
use_vignette Create a vignette
usethis-package usethis: Automate Package and Project Setup
browse-this Quickly browse to important package webpages
ci Continuous integration setup
use_build_ignore Add files to .Rbuildignore
use_code_of_conduct Add a code of conduct
use_github Connect a local repo with GitHub.
use_github_labels Create standard github labels for labelling issues.
use_rcpp Use Rcpp
use_readme_rmd Create README files.
use_tidy_style Style according to the tidyverse style guide
create_from_github Create a repo and project from GitHub
create_package Create a new package or project
use_news_md Create a simple
use_package Use specified package.
use_revdep Reverse dependency checks
use_rmarkdown_template Add an RMarkdown Template
use_usethis Make usethis available interactively
use_pipe Use magrittr's pipe in your package
No Results!

Last month downloads


License GPL-3
Encoding UTF-8
LazyData true
NeedsCompilation no
Packaged 2018-01-19 17:49:01 UTC; JennyVM
Repository CRAN
Date/Publication 2018-01-19 18:23:54 UTC

Include our badge in your README