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:

  1. venv (built into Python 3)

  2. conda (built into Anaconda/Miniconda)

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