Using Binder With Quarto

Quarto 1.4 Feature

This feature is new in Quarto 1.4. Download the latest version of Quarto at the download page

Overview

The Binder project provides a stack of tools designed to make it easy to share computing environments. Binder makes it straightforward to provide users with a link that restores the computing environment, and allows them to interact with your project code.

To use Binder with a Quarto project, you need to include a set of configuration files that describe your computational environment. Quarto can automatically create these files with the quarto use binder command. Run the command from within your Quarto project directory. The command will scan the project and determine the configuration files required to restore the environment. Commit the generated files to your project repository and your project is Binder-ready.

Keep reading for a more detailed walkthrough of the process, or skip ahead to learn about specifying Dependencies, the specific Configuration Files that may be generated, or how to Add a Link to Binder in your document.

Walkthrough

Consider a Quarto project that contains _quarto.yml and the document histogram.qmd which contains R executable code cells:

histogram.qmd
---
title: Histogram
---

```{r}
hist(rnorm(100))
```

To build an environment for this project, Binder needs to install Quarto and R, and should use the same Quarto and R versions as those used to build the project locally. A nice addition to the environment is an IDE that makes sense for the project content—with R code cells in a .qmd document RStudio would be a good choice.

To have Quarto generate the files describing the requirements, within the project directory, run:

Terminal
quarto use binder

The command will first detect and report the project configuration:

[✓] Detected Project configuration:

    Quarto       most recent prerelease
    JupyterLab   default               
    Engine       knitr                 
    R            4.3.2 (2023-10-31)    
    Editor       rstudio               

No files which provide dependencies were discovered. If you continue, no dependencies will be restored when running this project with Binder.

Learn more at:
https://www.quarto.org/docs/prerelease/1.4/binder.html#dependencies

? Do you want to continue? (Y/n) ›

Quarto detects the versions of Quarto and R in use, that our Quarto document uses the Knitr engine, and chooses an appropriate editor for the project.

Quarto will also detect files that describe R, Python or Julia dependencies - you can read more about these below in Dependencies. This project has none of these files, since the R code requires no additional packages.

If you continue, Quarto will list the files it will create:

The following files will be written:
┌─────────────┬────────────────────────────────────────┐
│ postBuild   │ Configures Quarto and supporting tools │
├─────────────┼────────────────────────────────────────┤
│ apt.txt     │ Installs Quarto required packages      │
├─────────────┼────────────────────────────────────────┤
│ runtime.txt │ Installs R and configures RStudio      │
└─────────────┴────────────────────────────────────────┘

 ? Continue? (Y/n) ›

After a final confirmation, Quarto will then write these files to the project:

Writing configuration files
[✓] postBuild
[✓] apt.txt
[✓] runtime.txt

These configuration files need to be committed to the project repository, along with the project files.

At mybinder.org you provide a link to the project repository. Binder builds the computational environment from the configuration files, and provides you a link where users can interact with the contents of your repository in the computing environment it has built.

You can try the Binder out for this project by following this Binder URL: https://mybinder.org/v2/gh/cwickham/binder-example/HEAD?urlpath=rstudio

The ?urlpath=rstudio at the end of this link, means the link will open an RStudio session. The Binder environment can take a little while to start up, but once it does, you should be in an RStudio instance with the project open. Since the computational environment has been configured, you can render the project in the usual ways (via the RStudio interface, or with quarto render in the Terminal).

Depending on the language and engine your project uses Quarto may generate files other than those shown for this project. You can read more about the files that quarto use binder might create below in Configuration Files.

Most projects will have additional dependencies such as R, Python or Julia packages. As mentioned, Quarto can detect the common files that specify these dependencies. You can read more about these files next in Dependencies.

Dependencies

When your project is restored to a new computational environment using Binder, any dependencies that the project has must also be restored. The quarto use binder command won’t detect computational dependencies from within your Quarto documents, but it will detect the files commonly used to describe them. The most common ways to describe them for the each environment are as follows:

Language Environment File
R renv renv.lock
R Binder R Config install.R
Python Conda environment.yml
Python Pip requirements.txt
Julia Pkg project.toml

Often these files are created as the result of using a virtual environment. See Virtual Environments for more about using Quarto with virtual environments.

Configuration Files

The following files may be generated by the quarto use binder command. Note that the command will prompt before overwriting any user files that it didn’t generate or any files that have been modified since they were generated.

postBuild

The post build script runs code after restoring the environment. This script is generated with commands required to ensure the proper version of Quarto is present in the environment, install any required tools like TinyTex or Chromium, and to configure VSCode and the Quarto extension for VSCode when applicable.

apt.txt

Provides a list of Debian packages to install with apt-get. This file is generated with all Quarto package dependencies.

runtime.txt

For R projects, this file will be generated with the appropriate R version, which is used to ensure that the same R version is present in the computational environment. This also will result in RStudio being configured and available when the computational environment is restored by a user.

install.R

For R projects, an install.R file will be generated to activate any renv environment that is present.

.jupyter

For projects using QMD files with the Jupyter engine, a .jupyter directory will be generated which will configure support for VSCode from within the JupyterLab environment.

You can read more about how Binder uses these configuration files in the Binder documentation.

Tip

Files generated by the quarto use binder command should be committed into your repo so they are available when the repo is used by Binder to restore the computational environment.