Tutorial

Learn how to use R4R through our comprehensive video tutorial and step-by-step text guide below.

r4r — Installation and Usage Tutorial

This tutorial explains how to install r4r and how to use it to create a fully reproducible execution environment for R code. Compared to the README, it provides more context and step-by-step guidance so that new users can easily follow along, even if they have little experience with Docker or reproducibility tooling.

Installing r4r

The easiest way to get started with r4r is to download the prebuilt binary from the project's release page. The tool currently supports Debian and Ubuntu, but it will also run on other distributions. On non-Debian systems, package resolution may not be available, and files will be copied directly instead of being mapped to system packages.

To install r4r, visit: GitHub Releases

Download the binary for your system and make it executable:

chmod +x r4r

You may optionally move the binary into your system's PATH so it can be called from anywhere:

sudo mv r4r /usr/local/bin/

If you prefer to build the tool from source, clone the repository and compile it using CMake:

git clone git@github.com:r-tooling/r4r.git
cd r4r
make install BUILD_TYPE=Release

After the build finishes, the executable will be available in the build/r4r directory.

Running r4r on an R Notebook

Once the tool is installed, you can use it to execute an R script or R Markdown notebook while tracing all filesystem accesses, R package usage, and system dependencies. r4r then bundles this information, generates a Dockerfile, and builds a self-contained Docker image capable of re-running the same computation in the future.

A minimal example looks like this:

r4r R -e "rmarkdown::render('path/to/notebook.Rmd')"     --output output     --result notebook.html

In this example, the tool executes the rendering of the notebook, traces the environment, and creates an output directory containing:

  • a generated Dockerfile,
  • a Makefile,
  • an archive of all captured input files,
  • metadata about package and system dependencies.

After generating those files, r4r automatically builds a Docker image (by default under the tag r4r/test) and runs it to re-execute the notebook inside a clean, isolated container. The produced HTML document is placed into output/result, so you can check whether the reproduced output matches the original one.

If you prefer that r4r only generates the files but does not build the Docker image automatically, you can pass the --skip-make flag. In that case, you can manually build and run the environment from inside the output directory:

make build
make copy

A Realistic Example

Here is a full example based on an actual workflow. It renders an R Markdown notebook located in a repository and stores both the output directory and the final HTML result in custom paths. It also makes use of a cached base image to speed up the build process:

build/r4r   --output repositories/output-projectname   --result result/repositories/projectname.html   --default-image-file repositories/ubuntu:24.04.cache   R -e "rmarkdown::render('repositories/projectname.Rmd')"

The meaning of each argument is straightforward:

  • --output specifies where r4r should write all captured files, metadata, and the generated Dockerfile.
  • --result indicates where the final rendered HTML file should be saved after re-executing the notebook inside the Docker image.
  • --default-image-file points to a cached base image, which avoids rebuilding the system base from scratch.
  • The trailing R -e "rmarkdown::render(...) is the actual command that r4r monitors and reproduces.

Uploading or Exporting the Docker Image

If you want to share the generated Docker image publicly, you may push it to a container registry:

docker push r4r/test

You can also export the image to a tar archive for long-term storage:

docker save r4r/test -o r4r-test.tar

Compressing the archive afterwards is recommended, as uncompressed Docker images can be large.

Verifying Reproducibility

After r4r re-runs the notebook inside the container, you will find the reproduced output in the output/result directory (or in the custom path you defined with --result). You can compare this output with your original notebook result to ensure that the execution was completely reproducible.

Minor differences may occasionally appear if underlying libraries change — this is especially true for HTML notebooks whose JavaScript dependencies may evolve over time.

Getting Help

More advanced options are available directly from the tool. You can view them with:

r4r --help

This will show a full overview of command-line arguments, including additional flags for verbosity, Docker naming, and detailed control over the tracing and build phases.

R4R Plugin Demo