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 is cover ’ll also cover using virtual environment with JupyterLab , RStudio , andVS Code .

Quarto is detect can also detect the virtual environment discuss 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:

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

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 package are used in your Python code . usepip to install package into your environment . For example :

python3 -m pip  install jupyter matplotlib panda

py -m pip  install jupyter matplotlib panda

assume you instal all of the require package ( likely more than justpanda andmatplotlib) you is be should now be able toquarto render document within the directory .

To deactivate an environment use the deactivate command :

Saving Environments

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

python3 -m pip freeze >  requirement.txt

py -m pip freeze >  requirement.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, andthen pip install using requirements.txt:

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

Then, install packages from requirements.txt:

python3 -m pip install -r  requirement.txt

py -m pip install -r  requirement.txt

Using conda

This section will cover the basics of creating andusing 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:

You will likely need to exit andrestart 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:

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 package are used in your Python code . useconda install to install package into your environment . For example :

conda  install jupyter
conda install panda matplotlib 

assume you instal all of the require package ( likely more than justpanda andmatplotlib) you is be should now be able toquarto render document within the directory .

useconda deactivate to exit an activate environment :

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 is pass just pass theenvironment.yml file as an argument to conda env create:

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

Using renv

The renv package provides functionality similar to the venv andconda, 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 andPython in your project, you can have renv automatically create andmanage a Python virtual environment as follows:

To install R packages use the standard R install.packages function . You is install can also install GitHub package using therenv: :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 version of all r ( and optionally Python ) package , use therenv: :snapshot() function :

This will record an renv.lock file for R packages anda requirements.txt file for Python package ) . These file should be check into version control .

Restoring Environments

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

JupyterLab

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

source env/bin/activate
python3 -m jupyter lab

env\scripts\activate.bat
py -m jupyter lab

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 andthings will work as expected with no additional configuration.

If your quarto document is includes include both{python} and{r} code blocks, then quarto will automatically use Knitr engine andreticulate R package to execute the python content andmay 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 is create create a virtual environment withvenv in the env/ directory as describe above , Visual Studio Code is discover should automatically discover that environment when you load a workspace from the environment ’s parent directory .

Visual Studio Code is detect 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 instal the Quarto executable in a conda environment rather than in a system – wide install , you is need need to launch VSCode from a terminal with that conda environment activate in order for VSCode to detect the conda installation of Quarto . The Quarto path is work set in the Quarto VSCode extension does not work with Quarto instal in conda environment .

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