reprex: turning R code into a copy-pasteable example that still runs

A reproducible example is a snippet that still runs when pasted

reprex is described as a package to render bits of R code for sharing, for example on GitHub or Stack Overflow. The name is a backronym the README spells out: a repr oducible ex ample, as coined by Romain Francois in a tweet from 2014.

The mechanism is what makes it more than a formatter. Given R code, from the clipboard, from a selection in RStudio, from an expression quoted or not, or from a file, reprex runs it through rmarkdown::render() with deliberate choices about the render arguments, the knitr options and the Pandoc options. The result is the runnable code plus its output.

The output arrives in several shapes. You get Markdown suitable for GitHub, Stack Overflow or Slack, or R code augmented with commented output, or plain HTML, or rich text, which the README marks as experimental. The result is returned invisibly, written to a file and, where possible, placed on the clipboard, and there is an HTML preview you can look at in the RStudio viewer or your default browser.

That combination of running and formatting is the whole value. A snippet you paste into an issue usually has one of two problems: it depends on objects the reader does not have, or it has no output at all so the reader cannot tell what it was supposed to produce. A reprex has neither problem, because the code was executed where the objects were defined, and the answer is right there in the paste.

The README states the goal in one line at the end of the example: anyone else can copy, paste, and run this immediately.

The default venue is GitHub, and the other venues are mostly aliases

The default target venue for reprex is GitHub, and the example in the README shows exactly what that produces. You copy some code to the clipboard, call reprex(), and the preview opens while the relevant Markdown lands on your clipboard.

The rendered result interleaves the code with its output using the knitr comment prefix, which is the same convention RStudio uses for its own output:

``` r (y <- 1:4) #> [1] 1 2 3 4 mean(y) #> [1] 2.5 ```

That format is the one GitHub renders as a code block with syntax highlighting, and it is also what a reader gets if they copy it back into their console.

The other venues need a word of caution, and the README is explicit. In addition to GitHub, this Markdown also works on Stack Overflow and Discourse, but those venues can be formally requested with venue = "so" and venue = "ds", and they are just aliases for venue = "gh". That is a useful thing to know before you assume a Stack Overflow flavour is tuned for Stack Overflow, because the answer is that it is the same Markdown and it is up to you to pick the right fences when you paste.

Two venues are genuinely different. venue = "slack" produces Markdown optimised for Slack messages, and venue = "R" produces a runnable R script with the output carried as comments, which the README points at for Slack code snippets and email. venue = "html" gives plain HTML for sites that do not support Markdown. And venue = "rtf" prepares unrendered, syntax-highlighted snippets for Keynote or PowerPoint, which the README still labels experimental and points to a separate article about.

The other arguments are the ones you will actually reach for. The wd argument sets the working directory, so reprex(wd = ".") asks for the current one, which matters when the code reads files. session_info = TRUE appends session information, which is the R equivalent of attaching a version header to a bug report. And by default figures are uploaded to imgur with the resulting URL dropped into an inline image tag, which is a detail worth knowing about before you use it on a machine where outbound uploads are not welcome.

Input can come from the clipboard, an expression, a string or a file

The clipboard is the default route, but the package is not limited to it, and the alternatives are where the package becomes scriptable.

reprex(mean(rnorm(10))) takes the code from an expression, evaluated in place. reprex(input = "mean(rnorm(10))\n") takes it from a character vector, detected by length or by a terminating newline. reprex(input = "my_reprex.R") takes it from a file. And the RStudio add-ins let you use the selected text or the current file, which is the ergonomic path for people who do not want to touch the console.

The character vector input has a detail that is easy to miss and useful to know. Leading prompts are stripped from the input source, so reprex(input = "> median(1:3)\n") produces the same output as reprex(input = "median(1:3)\n"). In other words, you can paste the raw console transcript, prompts and all, and get a clean reprex out of it.

That is the bridge to the three functions at the end of the README, which go the other way. reprex_invert() is the opposite of reprex(), taking a reprex apart. reprex_clean() produces clean runnable code from wild-caught reprexes, for example when you copy and paste from GitHub or Stack Overflow. And reprex_rescue() does the same for copy and paste from the R console, which is the messy case where the console has lost its structure.

Together with the wd and session_info arguments, this is a small toolkit for the boring half of reproducibility work: getting a question into a form that someone else can actually answer.

Figures go to imgur by default, and the working directory has to be right

Two behaviours in reprex are easy to miss and both cause confusion the first time they happen.

The first is figure handling. By default, figures are uploaded to imgur and the resulting URL is dropped into an inline image tag. That is a sensible default for the tool's main use, which is a question about a plot on a forum, and it means you do not have to manage attachments. It is also a network upload to a third-party host triggered by a function call, which matters on a machine with restricted egress, and it means the rendered example depends on a service outside your control.

The second is the working directory. The README says that if you really need to reprex in a specific directory, use the wd argument, and gives reprex(wd = ".") as the way to request the current working directory. In practice this is the fix for the most common reprex failure, which is code that reads a file that is not where the session happens to be pointing.

The session_info argument belongs in the same category of small features that decide whether the resulting paste is useful to somebody else. Appending session information with session_info = TRUE gives the reader the R version and the loaded packages, which is the difference between a reproducible example and a snippet that worked on someone else's machine last Tuesday.

The venue list has one more entry worth separating out. The experimental rtf venue produces unrendered, syntax-highlighted code snippets for Keynote or PowerPoint, and the README links to a separate article on it. It is the one output format that is not a text format, and the one most likely to have rough edges.

Installation is two commands, and the Linux clipboard needs a helper

Installing from CRAN takes one line:

``` r install.packages("reprex")

And there is a development version from GitHub, installed through pak, with the pak install line itself commented out in the README so you can read it before running it:

r # install.packages("pak") pak::pak("tidyverse/reprex") ```

The platform caveat is the one that catches people out. On Linux you probably want to install xclip or xsel so reprex can access the X11 clipboard. The README is careful to call this nice to have but not mandatory, since the usual sudo apt-get install or sudo yum install methods work for both, and because reprex also writes the result to a file and returns it invisibly, a missing clipboard bridge degrades the experience rather than breaking it.

The package sits in the tidyverse organisation, and the topics attached to the repository are github, r, reproducibility, rmarkdown and stackoverflow, which is the list of things it is for. The homepage is reprex.tidyverse.org, and the repository contains a pkgdown site configuration, vignettes, a revdep directory for reverse dependency checks, and a tests directory, so the package is documented and tested the way the rest of the tidyverse is.

The development story is worth noting for anyone who wants to help. The README lists a number of RStudio add-ins and features, and the package is a normal CRAN-published R package with a DESCRIPTION file, a NAMESPACE, generated man pages and a pkgdown site, so contributions follow the usual R package conventions rather than anything unusual.

Editorial conclusion

reprex is worth adopting the moment you file a question about R code anywhere, because it removes the two failure modes of a pasted snippet, a missing object and a missing output, at the cost of one function call. It is the wrong tool for a full analysis report, where R Markdown or Quarto is the better instrument, and it is the wrong tool if you cannot have your figures uploaded somewhere, since by default they go to imgur and the resulting URL is dropped into an inline image tag. Before you rely on it, verify three things yourself: that the venue you post to is one of the supported targets, since the Stack Overflow and Discourse venues are documented as aliases for the GitHub formatting, that the clipboard bridge works on your platform, since on Linux that needs xclip or xsel, and that the licence position suits you, because the repository licence is recorded as a custom one that GitHub cannot classify.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. Releases
5. tidyverse/reprex on GitHub