# usethis: one function per repetitive R project setup task > usethis is an R workflow package from r-lib that automates the chores of starting a project: creating a package skeleton, adding a licence, writing a README, scaffolding testthat, saving data and initialising git. It is chatty by design, and it is the tool most R developers reach for before they have written any of their own code. **r-lib/usethis** — Set up commonly used 📦 components - Repository: https://github.com/r-lib/usethis - Website: https://usethis.r-lib.org/ - Stars: 925 · Forks: 314 - Language: R - License: NOASSERTION - Published: 2026-10-20 · Updated: 2026-10-20 · Language: en - Canonical page: https://hysenlabs.com/projects/r-lib-usethis ## A workflow package for the chores of starting a project usethis is described as a workflow package that automates repetitive tasks that arise during project setup and development, both for R packages and for non-package projects. The repository description is shorter: set up commonly used components. That is the whole idea, and it is narrower than it first sounds. It does not write your analysis, it does not manage dependencies at run time and it does not replace any part of devtools. It creates and edits the files that every R project needs and that everybody gets subtly wrong by hand: a DESCRIPTION with the right fields, a licence file, a README, a NEWS file, a testthat scaffold, the data directory with the LazyData switch set, and a git repository with a sensible .gitignore. The README notes that many usethis functions are also applicable to analytical projects that are not packages, which is the more interesting use for most people. A data analysis project still wants a README, a licence, a git repo and a folder for figures and data, and the functions that create those work the same way whether or not a DESCRIPTION is involved. The audience is therefore broad, which is also why the package sits in the r-lib orbit alongside the tidyverse tooling. The homepage is usethis.r-lib.org, and the README badge marks the package lifecycle as stable, which in the r-lib scheme means the API is not going to be reshaped underneath you. ## The active project decides what gets modified Most use_* functions operate on the active project, which the README defines literally as a directory on your computer. If you have just used usethis to create a new package or project, that is the active project. Otherwise usethis verifies that the current working directory is, or is below, a valid project directory, and that becomes the active project. That is a deliberate design decision, and it is the one thing to understand before using the package on an existing codebase. usethis will not ask which directory to touch on every call. It infers it, and it changes the working directory as a side effect when you create a project. If the inference is not what you want, the README points to proj_get() and proj_sitrep() to query the project manually, with more detail in the documentation under the project utilities reference. A few functions have no strong connection to a project at all and expect you to provide a path. The output is chatty by design, and the README explains the convention: a check mark indicates something usethis has done for you, and an empty box indicates that you will need to do some work yourself. The second symbol is the more valuable one. In the example session, adding a package to Suggests produces two empty-box tasks, telling you to test whether the package is installed with requireNamespace and then refer to it directly with the double colon syntax. That is usethis being a teaching tool as much as an automation tool. It does the mechanical part and hands you the judgement. ## create_package writes a full skeleton in one call The example session starts by creating a package in a temporary directory: ```r library(usethis) # Create a new package ------------------------------------------------- path <- file.path(tempdir(), "mypkg") create_package(path) ``` The output shows what happens next. The directory is created, the active project is set to it, an R/ directory is made, and a DESCRIPTION is written with a title, a version of 0.0.0.9000, an Authors@R entry parsed with the author marked as aut and cre, a one paragraph Description, a License field pointing at the use_mit_license and use_gpl3_license helpers, a Config/roxygen2/version of 8.1.0, Encoding UTF-8 and Roxygen set to use markdown. A NAMESPACE file is written as well. Two things in that output are worth pausing on. The version 0.0.0.9000 is the conventional placeholder for a package that has not been released yet, and the Authors@R field is written in the structured form that R itself understands, rather than as free text in a Maintainer field. After creating the package the session calls proj_activate(path) again, with a comment explaining that it is only needed since the session is not interactive. That is a useful detail: in an interactive session the active project follows along, but in a script you have to re-activate it explicitly after a creation call, because the creation itself leaves the active project unset. The result is a package skeleton that already satisfies the conventions CRAN expects, which is the practical value of the function. It is not an empty directory with an idea in it; it is the shape a package is supposed to have. ## Licence, README, NEWS and tests as separate calls After creation, the rest of the setup is a series of small, independent calls. Each one edits an existing file rather than rewriting the project, which is what lets them be combined freely: ```r use_mit_license("My Name") use_package("rmarkdown", "Suggests") use_readme_md() use_news_md() use_test("my-test") ``` The licence call writes the LICENSE and LICENSE.md files, adds MIT + file LICENSE to the License field of DESCRIPTION, and adds the pattern to .Rbuildignore so the licence text is not copied into the built package. That last step is the kind of detail you would otherwise discover when your first CRAN submission fails. use_test adds testthat to the Suggests field, sets the testthat edition to 3, creates tests/testthat/ and writes both the runner file and a test file named after the test you asked for. It then leaves you a task to edit that test file, because an empty test is a placeholder. use_readme_md writes a README.md and leaves you the job of adding installation instructions, and use_news_md writes NEWS.md. Both are reminders rather than content: the tool creates the file and hands the writing back to you. The pattern holds across the whole package. usethis creates the structure, fills in the parts that have a canonical answer, and marks the parts that need your judgement. ## use_data and the LazyData convention Saving data through usethis is the one place where the tool also changes the package metadata, and it is worth understanding because it modifies how the package loads. In the example, two variables are created and then passed to use_data: ```r x <- 1 y <- 2 use_data(x, y) ``` The output records several coordinated changes. R is added to the Depends field of DESCRIPTION, a data/ directory is created, LazyData is set to true in DESCRIPTION, the objects are saved to data/x.rda and data/y.rda, and a task is left for you to document the data. Adding R to Depends is the part that surprises people. It is a heavier requirement than it looks: it means the package depends on the base R package being available, not just on R itself. The LazyData setting is the older R convention that lets the data be available to the user without an explicit load call, and it is the mechanism that makes data/x.rda appear as a dataset in the loaded package rather than as a file on disk. The documentation task is not optional in practice. Data in a package has to be described so that the help pages and the data listing work, and usethis deliberately leaves that to you, pointing at the data documentation page in the R packages book. The git call is the last step in the example. It initialises the repository and adds a set of entries to .gitignore, including .Rproj.user, .Rhistory, .RData, .httr-oauth, .DS_Store and .quarto. Two of those are worth understanding: .RData holds the saved R session state, and .httr-oauth is where the httr package caches OAuth tokens, so ignoring it is a credential hygiene measure as much as a tidiness one. ## Release cadence, installation paths and the licence file The package is on CRAN, and the README gives both installation routes. The released version comes from CRAN with install.packages("usethis"), and the development version from GitHub through pak, which the example shows with the install line for pak commented out: ```r install.packages("usethis") ``` ```r # install.packages("pak") pak::pak("r-lib/usethis") ``` The release record shows a deliberate rhythm. v3.2.2 was published on 2026-09-11, preceded by v3.2.1 on 2025-09-06 and v3.2.0 on 2025-08-28. So the 3.2 line has been in place for more than a year with a patch release in September 2026, and the repository is not archived with the last push on 2026-10-15. The repository layout shows the tooling around the package. There is a README.Rmd and a generated README.md, the pkgdown/ directory and _pkgdown.yml for the documentation site, a revdep/ directory for reverse dependency checks, vignettes/ for the longer guides, tests/ for the test suite, and an air.toml file, which is the formatter configuration for the air formatter used on this codebase. There is also a principles.md file, an AGENTS.md for automated agents, and cran-comments.md for the CRAN submission notes. On licensing, the licence field on the repository reports a custom licence that GitHub cannot classify, and the tree contains both a LICENSE file and a LICENSE.md. That is the arrangement usethis itself uses when it adds a licence to your package, as the MIT example shows, so the same files govern the tool and the packages it configures. As with the other r-lib projects, the licence text is permissive, but the dual file naming is worth checking in your own compliance tooling rather than assuming. ## Conclusion usethis suits an R developer starting a package or an analysis project who wants a conventional, well formed skeleton without memorising every file an R package is supposed to contain. It does not suit someone whose project structure is deliberately unusual, since the defaults encode one house style, and it does not replace reviewing what the tool wrote. Before adopting, install it with install.packages("usethis"), create a package in a temporary directory with create_package(), then open the generated DESCRIPTION and .gitignore by hand, because the value of the tool is the shape it gives you, not the code it writes for you. ## FAQ ### What is usethis and what does it automate? usethis is a workflow package that automates repetitive tasks that arise during project setup and development, for both R packages and non-package projects. It creates and edits files such as DESCRIPTION, NAMESPACE, licence files, README.md, NEWS.md, the testthat scaffold, the data directory and a git repository with a .gitignore. ### How do I install usethis? Install the released version from CRAN with install.packages("usethis"), or the development version from GitHub with pak::pak("r-lib/usethis"), which requires the pak package. ### What is the active project in usethis? Most use_* functions operate on the active project, which is a directory on your computer. It is set when you create a package or project, and otherwise usethis verifies that the current working directory is or is below a valid project directory. You can query it with proj_get() or proj_sitrep(). ### What does use_data do to a package? It adds R to the Depends field of DESCRIPTION, creates the data/ directory, sets LazyData to true in DESCRIPTION, and saves the objects to .rda files in that directory. The README leaves you a task to document the data afterwards. ### What do the check mark and empty box in usethis output mean? The README explains that usethis is chatty and uses a check mark for something it has done for you and an empty box for something you will need to do yourself, such as editing a generated test file or adding installation instructions to the README. ## Sources - [Issues](https://github.com/r-lib/usethis/issues) - [Project website](https://usethis.r-lib.org/) - [README](https://github.com/r-lib/usethis/blob/main/README.md) - [Releases](https://github.com/r-lib/usethis/releases) - [r-lib/usethis on GitHub](https://github.com/r-lib/usethis) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/r-lib-usethis