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 in to 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 environment will be created as a sub-directory of the project).

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

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
Windows
py -m venv env
Mac/Linux
python3 -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
Windows
(Command)
env\Scripts\activate.bat
Windows
(PowerShell)
env\Scripts\Activate.ps1
Mac/Linux
source env/bin/activate
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:

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. ip to install packages into your environment. For example:

Platform Command
Windows
py -m pip install matplotlib pandas
Mac/Linux
python3 -m pip install 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:

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
Windows
py -m pip freeze > requirements.txt
Mac/Linux
python3 -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
Windows
py -m pip install -r requirements.txt
Mac/Linux
python3 -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:

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
Windows
(Command)
conda init cmd.exe
Windows
(PowerShell)
conda init powershell
Linux / Older Mac
(Bash)
conda init bash
Newer Mac
(Zsh)
conda init zsh

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
Windows
conda activate .\env
Mac/Linux
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:

conda install jupyterlab
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:

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:

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 create:

conda create --prefix env -f environment.yml

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.pacakges("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
Windows
(Command)
env\Scripts\activate.bat
py -m jupyter lab
Windows (PowerShell)
env\Scripts\Activate.ps1
py -m jupyter lab
Mac/Linux
source env/bin/activate
python3 -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 daily build of RStudio from https://dailies.rstudio.com/ (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 ust 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.

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

Note that this applies only to venv not Conda environments (which have a separate mechansim for binding to the current VS Code session).

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