Virtual Environments

Virtual environments provide a project-specific version of installed packages. This both helps you to faithfully reproduce your environment (e.g. if you are collaborating with a colleague or deploying to a server) as well as isolate the use of packages so that upgrading a package in one project doesn’t break other projects.

There are several popular flavors of virtual environment, we will cover the following ones here:

venv (built into Python 3)
conda (built into Anaconda/Miniconda)
renv (package for managing R environments)

Below we’ll provide some example workflows for using these tools with Quarto. In these examples we’ll assume that you are already within a project directory that contains Quarto documents (so the virtual environment will be created as a sub-directory of the project).

We’ll also cover using virtual environments with JupyterLab, RStudio, and VS Code.

Quarto can also detect the virtual environments discussed on this page to configure your project for Binder. Read more at Using Quarto with Binder.

Using venv

Here we’ll provide a brief run through of creating a venv for a Quarto project. See the full documentation on using virtual environments with Python for additional details.

To create a new Python 3 virtual environment in the directory env:

Platform	Command
Mac/Linux	Terminal `python3 -m venv env`
Windows	Terminal `py -m venv env`

To use the environment you need to activate it. This differs slightly depending on which platform / shell you are using:

Shell	Command
Mac/Linux	Terminal `source env/bin/activate`
Windows (Command)	Terminal `env\Scripts\activate.bat`
Windows (PowerShell)	Terminal `env\Scripts\Activate.ps1`

PowerShell Note

Note that you may receive an error about running scripts being disabled when activating within PowerShell. If you get this error then execute the following command:

Terminal

Set-ExecutionPolicy -ExecutionPolicy Unrestricted -Scope CurrentUser

Once you’ve activated the environment, you need to ensure that you have the packages required to render your documents. This will typically encompass jupyter / jupyterlab plus whatever other packages are used in your Python code. Use pip to install packages into your environment. For example:

Platform	Command
Mac/Linux	Terminal `python3 -m pip install jupyter matplotlib pandas`
Windows	Terminal `py -m pip install jupyter matplotlib pandas`

Assuming you installed all of the required packages (likely more than just pandas and matplotlib) you should now be able to quarto render documents within the directory.

To deactivate an environment use the deactivate command:

Terminal

deactivate

Saving Environments

To make your environment reproducible, you need to create a requirements.txt file that enumerates all of the packages in use. To do this use the pip freeze command:

Platform	Command
Mac/Linux	Terminal `python3 -m pip freeze > requirements.txt`
Windows	Terminal `py -m pip freeze > requirements.txt`

You should generally check the requirements.txt file into version control.

Restoring Environments

To reproduce the environment on another machine you create an empty environment, activate it, and then pip install using requirements.txt:

First, follow the instructions above for creating and activating a virtual environment for your platform/shell.

Then, install packages from requirements.txt:

Platform	Command
Mac/Linux	Terminal `python3 -m pip install -r requirements.txt`
Windows	Terminal `py -m pip install -r requirements.txt`

Using conda

This section will cover the basics of creating and using conda environments with Quarto projects. See this article on managing project specific environments with Conda for additional details.

To create a new environment in the directory env:

Terminal

conda create --prefix env python

If this is the first time you’ve used conda in your shell, you may need to execute one of the following commands before using other conda tools:

Shell	Command
Newer Mac (Zsh)	Terminal `conda init zsh`
Linux / Older Mac (Bash)	Terminal `conda init bash`
Windows (Command)	Terminal `conda init cmd.exe`
Windows (PowerShell)	Terminal `conda init powershell`

You will likely need to exit and restart your terminal for conda init to be reflected in your session.

To use the environment you need to activate it, which you do as follows:

Platform	Command
Mac/Linux	Terminal `conda activate ./env`
Windows	Terminal `conda activate .\env`

Once you’ve activated the environment, you need to ensure that you have the packages required to render your documents. This will typically encompass jupyter / jupyterlab plus whatever other packages are used in your Python code. Use conda install to install packages into your environment. For example:

Terminal

conda install jupyter
conda install pandas matplotlib

Assuming you installed all of the required packages (likely more than just pandas and matplotlib) you should now be able to quarto render documents within the directory.

Use conda deactivate to exit an activated environment:

Terminal

conda deactivate

Saving Environments

To make your environment reproducible, you need to create a environment.yml file that enumerates all of the packages in use. Do this using the conda env export command:

Terminal

conda env export > environment.yml

You should generally check the environment.yml file into version control.

Restoring Environments

To reproduce the environment on another machine you just pass the environment.yml file as an argument to conda env create:

Terminal

conda env create --prefix env -f environment.yml

More information

For more on conda’s environment.yml, see Conda’s Managing Environments documentation.

Using renv

The renv package provides functionality similar to the venv and conda, but for R packages. To create a new renv environment, install the renv package from CRAN then call the renv::init() function:

install.packages("renv")
renv::init()

As part of initialization, your .Rprofile file is modified to ensure that the renv is activated automatically at the start of each R session.

If you plan on using both R and Python in your project, you can have renv automatically create and manage a Python virtual environment as follows:

renv::use_python()

To install R packages use the standard R install.packages function. You can also install GitHub packages using the renv::install function. For example:

install.packages("ggplot2")      # install from CRAN
renv::install("tidyverse/dplyr") # install from GitHub

To install Python packages just use pip as described above from the built-in RStudio terminal.

Saving Environments

To record the current versions of all R (and optionally Python) packages, use the renv::snapshot() function:

renv::snapshot()

This will record an renv.lock file for R packages and a requirements.txt file for Python packages). These files should be checked into version control.

Restoring Environments

To reproduce the environment on another machine use the renv::restore() function:

renv::restore()

JupyterLab

To use Jupyter or JupyterLab within a Python virtual environment you just need to activate the environment and then launch the Jupyter front end. For example:

Shell	Command
Mac/Linux	Terminal `source env/bin/activate python3 -m jupyter lab`
Windows (Command)	Terminal `env\Scripts\activate.bat py -m jupyter lab`
Windows (PowerShell)	Terminal `env\Scripts\Activate.ps1 py -m jupyter lab`

All of the Python packages installed within the env will be available in your Jupyter notebook session. The workflow is similar if you are using conda environments.

RStudio

If you are using Quarto within RStudio it is strongly recommended that you use the current release of RStudio from https://www.rstudio.com/products/rstudio/download/ (the documentation below assumes you are using this build).

renv

If you are using renv, RStudio will automatically do the right thing in terms of binding Quarto to the R and/or Python packages in your project-local environments.

If you need to install R packages, use install.packages; if you need to install Python packages, simply use pip or conda within the terminal as described above.

venv / condaenv

RStudio will automatically activate any venv or condaenv that it finds within a project directory. Just be sure to create an RStudio project within the same directory where you created your env and things will work as expected with no additional configuration.

Using python and r together

If your quarto document includes both {python} and {r} code blocks, then quarto will automatically use Knitr engine and reticulate R package to execute the python content and may use a different version of python than is included in your environment. To direct RStudio to use a specific version of python, you can specify explicitly a path to an installed python version, e.g. by adding the following line to the .Rprofile file in your project directory:

Sys.setenv(RETICULATE_PYTHON = "/path/to/your/env/bin/python")

More about Python Version Configuration for reticulate at https://rstudio.github.io/reticulate/articles/versions.html

If you need to install Python packages, simply use pip or conda within the terminal as described above.

VS Code

If you create a virtual environment with venv in the env/ directory as described above, Visual Studio Code should automatically discover that environment when you load a workspace from the environment’s parent directory.

Visual Studio Code will also automatically detect a conda environment, but you need to bind it to the current session with the Python: Select Interpreter command.

If you have installed the Quarto executable in a conda environment rather than in a system-wide install, you need to launch VSCode from a terminal with that conda environment activated in order for VSCode to detect the conda installation of Quarto. The Quarto path setting in the Quarto VSCode extension does not work with Quarto installed in conda environments.

You can read more about VS Code support for Python virtual environments here: https://code.visualstudio.com/docs/python/environments.