虚拟环境

虚拟环境提供了项目特定的已安装包版本。这不仅有助于你忠实地重现你的环境（例如，如果你与同事合作或在服务器上部署），还能隔离包的使用，使得在一个项目中升级包不会破坏其他项目。

有几种流行的虚拟环境类型，我们将在这里介绍以下几种：

  1. venv（内置于 Python 3）

  2. conda（内置于 Anaconda/Miniconda）

  3. renv（用于管理 R 环境的包）

下面我们将提供一些使用这些工具与 Quarto 结合的示例工作流程。在这些示例中，我们假设你已经在包含 Quarto 文档的项目目录中（因此虚拟环境将作为项目的子目录创建）。

我们还将介绍如何在使用 JupyterLab、RStudio 和 VS Code 时使用虚拟环境。

Quarto 还可以检测本页讨论的虚拟环境，以配置你的项目用于 Binder。更多信息请阅读 使用 Quarto 与 Binder。

使用 venv

这里我们将简要介绍为 Quarto 项目创建 venv 的过程。有关使用虚拟环境的更多详细信息，请参阅 完整文档。

要在目录 env 中创建一个新的 Python 3 虚拟环境：

平台 命令
Mac/Linux 
Terminal
python3 -m venv env
Windows 
Terminal
py -m venv env

要使用该环境，你需要激活它。这会根据你使用的平台/shell 略有不同：

Shell 命令
Mac/Linux 
Terminal
source env/bin/activate
Windows
(Command)		 
Terminal
env\Scripts\activate.bat
Windows
(PowerShell)		 
Terminal
env\Scripts\Activate.ps1
PowerShell 注意事项

请注意，当你在 PowerShell 中激活时，可能会收到关于运行脚本被禁用的错误。如果你遇到此错误，请执行以下命令：

Terminal
Set-ExecutionPolicy -ExecutionPolicy Unrestricted -Scope CurrentUser

激活环境后，你需要确保安装了渲染文档所需的包。这通常包括 jupyter / jupyterlab 以及你的 Python 代码中使用的其他包。使用 pip 将包安装到你的环境中。例如：

平台 命令
Mac/Linux 
Terminal
python3 -m pip install jupyter matplotlib pandas
Windows 
Terminal
py -m pip install jupyter matplotlib pandas

假设你已经安装了所有必需的包（可能不仅仅是 pandas 和 matplotlib），你现在应该能够在该目录中使用 quarto render 渲染文档。

要停用环境，请使用 deactivate 命令：

Terminal
deactivate

保存环境

为了使你的环境可重现，你需要创建一个 requirements.txt 文件，列出所有正在使用的包。为此，请使用 pip freeze 命令：

平台 命令
Mac/Linux 
Terminal
python3 -m pip freeze > requirements.txt
Windows 
Terminal
py -m pip freeze > requirements.txt

通常你应该将 requirements.txt 文件提交到版本控制中。

恢复环境

要在另一台机器上重现环境，你可以创建一个空环境，激活它，然后使用 requirements.txt 进行 pip install：

首先，按照上面的说明为你的平台/shell 创建并激活虚拟环境。

然后，从 requirements.txt 安装包：

平台 命令
Mac/Linux 
Terminal
python3 -m pip install -r requirements.txt
Windows 
Terminal
py -m pip install -r requirements.txt

使用 conda

本节将介绍使用 conda 环境与 Quarto 项目的基本知识。有关更多详细信息，请参阅这篇关于使用 Conda 管理项目特定环境的文章。

要在 env 目录中创建新环境：

Terminal
conda create --prefix env python

如果你是第一次在 shell 中使用 conda，你可能需要在使用其他 conda 工具之前执行以下命令之一：

Shell 命令
较新的 Mac  | {.bash filename="Terminal"} | (Zsh) | conda init zsh |
Linux / 较旧的 Mac
(Bash)		 
Terminal
conda init bash
Windows
(Command)		 
Terminal
conda init cmd.exe
Windows
(PowerShell)		 
Terminal
conda init powershell

你可能需要退出并重新启动终端，以便 conda init 在你的会话中生效。

要使用该环境，你需要激活它，方法如下：

平台 命令
Mac/Linux 
Terminal
conda activate ./env
Windows 
Terminal
conda activate .\env

一旦激活了环境，你需要确保安装了渲染文档所需的包。这通常包括 jupyter / jupyterlab 以及你的 Python 代码中使用的其他包。使用 conda install 将包安装到你的环境中。例如：

Terminal
conda install jupyter
conda install pandas matplotlib

假设你已经安装了所有必需的包（可能不仅仅是 pandas 和 matplotlib），你现在应该能够在目录中使用 quarto render 渲染文档。

使用 conda deactivate 退出激活的环境：

Terminal
conda deactivate

保存环境

为了使你的环境可重现，你需要创建一个 environment.yml 文件，列出所有正在使用的包。使用 conda env export 命令来完成此操作：

Terminal
conda env export > environment.yml

通常你应该将 environment.yml 文件提交到版本控制中。

恢复环境

要在另一台机器上重现环境，只需将 environment.yml 文件作为参数传递给 conda env create：

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

更多信息

有关 conda 的 environment.yml 的更多信息，请参阅 Conda 的 管理环境 文档。

使用 renv

renv 包提供了类似于 venv 和 conda 的功能，但适用于 R 包。要创建一个新的 renv 环境，从 CRAN 安装 renv 包，然后调用 renv::init() 函数：

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

作为初始化的一部分，你的 .Rprofile 文件会被修改，以确保在每次 R 会话开始时自动激活 renv。

如果你计划在项目中同时使用 R 和 Python，你可以让 renv 自动创建和管理一个 Python 虚拟环境，如下所示：

renv::use_python()

要安装 R 包，使用标准的 R install.packages 函数。你也可以使用 renv::install 函数从 GitHub 安装包。例如：

install.packages("ggplot2")      # 从 CRAN 安装
renv::install("tidyverse/dplyr") # 从 GitHub 安装

要安装 Python 包，只需使用如上所述的 pip，从内置的 RStudio 终端中操作。

保存环境

要记录当前所有 R（和可选的 Python）包的版本，使用 renv::snapshot() 函数：

renv::snapshot()

这将记录一个 renv.lock 文件用于 R 包，以及一个 requirements.txt 文件用于 Python 包。这些文件应该提交到版本控制中。

恢复环境

要在另一台机器上重现环境，使用 renv::restore() 函数：

renv::restore()

JupyterLab

要在 Python 虚拟环境中使用 Jupyter 或 JupyterLab，只需激活环境并启动 Jupyter 前端。例如：

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

在 env 中安装的所有 Python 包都将在你的 Jupyter 笔记本会话中可用。如果你使用的是 conda 环境，工作流程类似。

RStudio

如果你在 RStudio 中使用 Quarto，强烈建议你使用 https://www.rstudio.com/products/rstudio/download/ 的 当前版本 的 RStudio（下面的文档假设你使用的是这个版本）。

renv

如果你使用 renv，RStudio 会自动正确地将 Quarto 绑定到你的项目本地环境中的 R 和/或 Python 包。 如果你需要安装 R 包，使用 install.packages；如果你需要安装 Python 包，只需在终端中使用 pip 或 conda，如上所述。

venv / condaenv

RStudio 会自动激活在项目目录中找到的任何 venv 或 condaenv。只需确保在创建 env 的同一目录中创建一个 RStudio 项目，一切将按预期工作，无需额外配置。

同时使用 Python 和 R

如果你的 Quarto 文档包含 {python} 和 {r} 代码块，Quarto 将自动使用 Knitr 引擎和 reticulate R 包来执行 Python 内容，并且可能会使用与你的环境中不同的 Python 版本。要指示 RStudio 使用特定版本的 Python，你可以明确指定已安装的 Python 版本的路径，例如，通过在项目目录的 .Rprofile 文件中添加以下行：

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

更多关于 reticulate 的 Python 版本配置信息，请访问 https://rstudio.github.io/reticulate/articles/versions.html

如果你需要安装 Python 包，只需在终端中使用 pip 或 conda，如上所述。

VS Code

如果你按照上述说明在 env/ 目录中使用 venv 创建虚拟环境，当你从环境的父目录加载工作区时，Visual Studio Code 应该会自动发现该环境。

Visual Studio Code 也会自动检测 conda 环境，但你需要使用 Python: Select Interpreter 命令将其绑定到当前会话。

如果你在 conda 环境中安装了 Quarto 可执行文件，而不是系统范围的安装，你需要在激活该 conda 环境的终端中启动 VSCode，以便 VSCode 检测到 conda 安装的 Quarto。 Quarto VSCode 扩展中的 Quarto 路径设置不适用于安装在 conda 环境中的 Quarto。

你可以在这里阅读更多关于 VS Code 对 Python 虚拟环境的支持信息：https://code.visualstudio.com/docs/python/environments。