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 in to 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 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




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