Using Binder With Quarto

Pre-release Feature

This feature is new in the upcoming Quarto 1.4 release. To use the feature now, you’ll need to download and install the Quarto pre-release.

Overview

The Binder project provides a stack of tools designed to make it easy to share computing environments. When projects use best practices and are hosted online, Binder makes it straightforward to provide users with a link which restores the computing environment.

Quarto can now automatically create supporting files required to permit deployment of Quarto projects using Binder. Use the command quarto use binder from within a project directory to initialize your directory with required files.

Creating Binder Files

Use the command quarto use binder from within your Quarto project directory to generate files required to make your project available via Binder. The command will scan the project and based upon the specific configuration (Quarto version and tools, computational engines, data about dependencies and the computational environment), determine the configuration restore the environment.

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.

Dependencies

When your project is restored to a new computational environment using Binder, any dependencies that the project has must also be restored. There are a few different ways of documenting these dependencies so they may be restored. The most common for the each environment are as follows:

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

Configuration Files

The following files may be generated by the 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 are installed, and to configure VSCode and the Quarto extension for VSCode when applicable.

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 evironment 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.

apt.txt

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

.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.