styler reformats R code to the tidyverse style guide without rewriting it

The target is a style guide, not a personal preference

styler formats your code according to the tidyverse style guide, or your custom style guide, so you can direct your attention to the content of your code. The stated goals are to keep the coding style consistent across projects and to facilitate collaboration.

That framing is the whole argument for the package, and it is worth taking seriously rather than treating styler as one more formatter. A formatter that encodes one house style is a formatting opinion. A formatter that takes a style guide as input is a policy mechanism, and the value it delivers is not that the output looks a particular way, it is that a pull request no longer contains formatting arguments.

The package description calls the work non-invasive pretty printing of R code. Non-invasive is the load-bearing word. The intent of the formatting operation is to change layout without changing what the code means, and the tidyverse guide styler targets is a documented, public specification rather than a set of undocumented defaults, which is what makes the promise of preserving behaviour checkable by a reader who is not the author of the formatter.

Who it is for is fairly clear from the shape of the tool. It is for people who work in R with other people, on code long enough that its layout matters, and who would rather not spend review time on whitespace. It is also for teams that want formatting enforced in continuous integration, since a formatter that produces the same output for the same input can be run as a check, and the repository shows the tooling for that in its pre-commit configuration.

The project is part of the r-lib organisation, the homepage is styler.r-lib.org, and the README points at the tidyverse style guide as the reference it implements.

Three functions cover text, files and whole packages

The access points are named in the README, and they differ in what they take and what they return.

style_text() operates on code held in memory, which is the entry point for scripts, for a snippet pasted into the console, or for a unit test that asserts a formatted result. style_file() handles one file, which is the case when you are tidying a single script you inherited. style_pkg() handles a package, which is the case that matters for maintainers, since a package has a fixed layout, a directory structure and a convention that the whole set of files follows one style.

The distinction is not just convenience. A package is the unit where consistency matters most, because the files are read side by side and a single badly formatted file makes the others look wrong. Running style_pkg() over a package is a one-time migration that makes the diff of a formatting change large and the diff of every later change small.

There is a fourth path described as the RStudio Addin, demonstrated in the README with a recording, and the RStudio route is how most users meet the package because it turns formatting into a menu action on the current file or selection.

The README also points to a vignette named third-party-integrations, which documents access through various other tools. That is the file to read before wiring styler into an existing workflow, because it tells you which editors, hooks and pipelines already know how to call it, and how they expect to be configured. The function names are also the public API, so anything you script against them will break if the names change, and the repository has a NEWS.md and a versioned API directory to track that.

Install from CRAN, or take the development version from GitHub

The CRAN install is the standard one for any R package:

install.packages("styler")

If you want the development version, the README points to remotes, and the install is:

# install.packages("remotes")
remotes::install_github("r-lib/styler")

The commented line matters for a first run, since remotes is not a dependency of styler and has to be installed separately.

There are two documentation sites, and which one you want depends on the version you installed. The latest CRAN release is documented at styler.r-lib.org, and the GitHub development version is documented at styler.r-lib.org/dev/. That split is the practical reason to care about which copy you have installed, because the two sites describe different behaviour when the development version is ahead of the release.

The version picture is worth checking before you pin anything. The published releases are 1.10.1 on 2023-06-05, 1.10.2 on 2023-08-29 and 1.10.3 on 2024-04-07, and the repository was last pushed on 2026-09-29. So the CRAN copy is considerably older than the source tree, and installing from GitHub gives you work that has not been through a CRAN review cycle.

Neither of the two install paths is documented as requiring anything unusual, which is consistent with the package being a plain R package with no compiled code to build.

What the repository shows about how the package is put together

The tree is the standard layout of a CRAN-published R package, and reading it tells you where the interesting parts live.

DESCRIPTION and NAMESPACE are the package metadata and the exported interface. The NAMESPACE file is the contract: it declares what styler exports, so a function that is not there is internal, and a function that is there is something your code may depend on.

The R/ directory holds the source, and man/ holds the generated help pages, with the .Rd files that R renders into the help system. vignettes/ holds the long form documentation, and the third-party-integrations vignette the README points to lives there, alongside other articles that the package index links to.

The tests/ directory holds the test suite, and touchstone/ is a separate directory whose name refers to snapshot testing of R output, which is the natural way to test a formatter since the expected result of formatting an input is a fixed string. The .lintr file configures the lintr R package for the project's own source, and .pre-commit-config.yaml wires the repository's own formatting into git hooks, so the project formats itself with its own tool rather than describing the practice in prose.

Two files deserve a second look from a licensing point of view. The repository contains both LICENSE and LICENSE.md, and the licence field on the repository itself is marked as a custom licence that GitHub cannot classify. The README does not summarise the terms, so the authoritative text is the licence file in the repository, and that is the file to hand to whoever reviews licence terms for your organisation. This is not legal advice, it is a pointer to which document to read.

The rest of the tree follows the same convention: .Rbuildignore lists what should be excluded from the built package, .gitattributes and .gitignore handle the file handling, _pkgdown.yaml and pkgdown/ drive the documentation website, cran-comments.md holds the notes submitted with each CRAN release, and NEWS.md is the changelog.

A stable lifecycle badge and a package that formats itself

Two details in the README badges tell you about the project's standing. The lifecycle badge says stable, which in the r-lib lifecycle scheme means the package is finished in the sense that its interface is not expected to change in incompatible ways and it is not scheduled for removal. The CRAN status badge points at the current published version, and the build status badge points at the R CMD check workflow, which is the standard R package check.

The codecov badge for test coverage points at the main branch, which is a reasonable signal for a package whose entire value depends on behaving identically across a wide range of R code, since a formatter is only as trustworthy as the corpus of inputs it has been tested against.

The self-hosting point from the previous section deserves emphasis. A repository that formats its own source with the tool it ships, enforced through a pre-commit configuration, is making a statement about dogfooding that goes beyond a documentation claim. It also means the style rules the project enforces on itself are the ones the tidyverse guide describes, so a change in the formatter's behaviour shows up as a diff in the project's own code, which is a cheap way to see what a new version would change in your code.

That is worth doing deliberately rather than accidentally. Because a formatter can change layout of code you did not write, upgrading styler can produce a diff across an entire package. The project's own repository is a reasonable place to observe that, and NEWS.md is where a behavioural change would be recorded.

For a team, the practical point is that adopting styler is not only a matter of running it once. The consistency benefit only holds if the formatting is re-applied, either manually before review or automatically as a check, and a formatter whose output changes between versions makes that automation a source of noise unless the versions are pinned.

Where styler is the wrong tool

There are three cases where a formatter like this is the wrong answer, and they are worth naming before a team adopts it.

The first is a project with a deliberate house style that is not the tidyverse style guide. styler can take a custom style guide, so this is not a hard block, but a custom guide is a larger commitment than adopting an existing one, and the README gives no detail about how a custom guide is expressed, so the effort of authoring one falls on the adopting team.

The second is generated code. If a repository contains code that is written by a generator, formatting it is at best pointless and at worst harmful, because the next regeneration produces a diff that reverses the formatting. Nothing in styler distinguishes generated files from hand written ones, so excluding them is a job the project has to take on itself, usually by keeping generated output out of the linting and formatting path in the first place.

The third is a code base where whitespace is not the source of friction. styler addresses layout, and the README states its goal as letting you direct your attention to the content of your code. If the recurring review comments are about naming, about duplication or about unclear structure, running a formatter will reduce the noise without touching the actual problem, and the team will have bought a tool that is not the one it needed.

There is also a practical limit on the CRAN copy. The newest published release is 1.10.3 from 2024-04-07, so a team that wants the current behaviour of the formatter has to install from GitHub and accept that the result has not been through the CRAN review cycle.

Editorial conclusion

styler fits a team that has agreed on a style guide and wants it applied mechanically, particularly in a package or script collection where the formatting would otherwise drift between contributors, since the whole point is consistency rather than personal preference. It is the wrong tool for a project that has deliberately chosen a different house style, unless you point it at your own guide, and it is the wrong tool for code that is generated, since reformatting generated output creates diff noise. Before adopting, read the third-party integrations vignette to see which editors and hooks already call styler, check that the tidyverse conventions match what your team already writes, and note that the newest CRAN release is 1.10.3 from 2024-04-07 while the repository was pushed on 2026-09-29, so a GitHub install gives you newer behaviour than the CRAN copy.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. Releases
5. r-lib/styler on GitHub