가상 환경

가상 환경은 프로젝트별로 설치된 패키지 버전을 제공합니다. 이를 통해 환경을 충실히 재현할 수 있고(예: 동료와 협업하거나 서버에 배포할 때), 한 프로젝트에서 패키지를 업그레이드해도 다른 프로젝트가 깨지지 않도록 패키지 사용을 분리할 수 있습니다.

가상 환경에는 여러 인기 있는 유형이 있으며, 여기서는 다음을 다룹니다.

venv (built into Python 3)
conda (built into Anaconda/Miniconda)
renv (R 환경 관리 패키지)

아래에서는 Quarto에서 이 도구들을 사용하는 예시 워크플로를 제공합니다. 예시에서는 Quarto 문서가 포함된 프로젝트 디렉터리 안에 이미 있다고 가정합니다(따라서 가상 환경은 프로젝트의 하위 디렉터리로 생성됨).

JupyterLab, RStudio, Positron, VS Code에서 가상 환경을 사용하는 방법도 다룹니다.

Quarto는 이 페이지에서 다룬 가상 환경을 감지해 프로젝트를 Binder용으로 구성할 수도 있습니다. 자세한 내용은 Quarto에서 Binder 사용을 참고하세요.

venv 사용

여기서는 Quarto 프로젝트에서 venv를 만드는 과정을 간단히 살펴봅니다. 자세한 내용은 Python 가상 환경에 대한 전체 문서를 참고하세요.

env 디렉터리에 새 Python 3 가상 환경을 만들려면 다음을 실행합니다.

Platform	Command
Mac/Linux	Terminal `python3 -m venv env`
Windows	Terminal `py -m venv env`

환경을 사용하려면 활성화해야 합니다. 사용 중인 플랫폼/셸에 따라 방법이 조금씩 다릅니다.

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

PowerShell에서 활성화할 때 스크립트 실행이 비활성화되었다는 오류가 발생할 수 있습니다. 이 경우 다음 명령을 실행하세요.

Terminal

Set-ExecutionPolicy -ExecutionPolicy Unrestricted -Scope CurrentUser

환경을 활성화한 뒤에는 문서 렌더링에 필요한 패키지가 설치되어 있는지 확인해야 합니다. 보통 jupyter/jupyterlab과 Python 코드에서 사용하는 패키지가 포함됩니다. pip로 패키지를 설치하세요. 예:

Platform	Command
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 명령을 사용합니다.

Platform	Command
Mac/Linux	Terminal `python3 -m pip freeze > requirements.txt`
Windows	Terminal `py -m pip freeze > requirements.txt`

보통 requirements.txt 파일은 버전 관리에 포함해야 합니다.

환경 복원

다른 머신에서 환경을 재현하려면 빈 환경을 만들고 활성화한 뒤 requirements.txt로 pip install을 실행합니다.

먼저 위의 안내를 따라 해당 플랫폼/셸에 맞는 가상 환경을 생성하고 활성화합니다.

그 다음 requirements.txt에서 패키지를 설치합니다.

Platform	Command
Mac/Linux	Terminal `python3 -m pip install -r requirements.txt`
Windows	Terminal `py -m pip install -r requirements.txt`

conda 사용

이 섹션에서는 Quarto 프로젝트에서 conda 환경을 만들고 사용하는 기본을 다룹니다. 자세한 내용은 Conda로 프로젝트별 환경 관리 문서를 참고하세요.

env 디렉터리에 새 환경을 만들려면 다음을 실행합니다.

Terminal

conda create --prefix env python

셸에서 conda를 처음 사용한다면 다른 conda 도구를 사용하기 전에 다음 명령 중 하나를 실행해야 할 수 있습니다.

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`

conda init이 세션에 반영되려면 터미널을 종료하고 다시 시작해야 할 수 있습니다.

환경을 사용하려면 활성화해야 하며, 방법은 다음과 같습니다.

Platform	Command
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 파일은 버전 관리에 포함해야 합니다.

환경 복원

다른 머신에서 환경을 재현하려면 conda env create에 environment.yml 파일을 인자로 전달하면 됩니다.

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 함수로 설치합니다. GitHub 패키지는 renv::install 함수로 설치할 수 있습니다. 예:

install.packages("ggplot2")      # install from CRAN
renv::install("tidyverse/dplyr") # install from GitHub

Python 패키지는 위에서 설명한 대로 RStudio 내장 터미널에서 pip를 사용해 설치하면 됩니다.

환경 저장

현재 R(및 선택적으로 Python) 패키지 버전을 기록하려면 renv::snapshot() 함수를 사용합니다.

renv::snapshot()

이 과정은 R 패키지용 renv.lock 파일과 Python 패키지용 requirements.txt 파일을 기록합니다. 이 파일들은 버전 관리에 포함해야 합니다.

환경 복원

다른 머신에서 환경을 재현하려면 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/의 최신 릴리스를 사용하는 것을 강력히 권장합니다(아래 문서는 이 빌드를 사용한다고 가정합니다).

renv

renv를 사용한다면 RStudio가 프로젝트 로컬 환경의 R 및/또는 Python 패키지에 Quarto를 자동으로 올바르게 연결합니다.

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 버전을 사용하도록 하려면 프로젝트 디렉터리의 .Rprofile에 다음 줄을 추가해 설치된 Python 경로를 명시합니다.

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

reticulate의 Python 버전 구성에 대한 자세한 내용은 https://rstudio.github.io/reticulate/articles/versions.html을 참고하세요.

Python 패키지가 필요하면 위에서 설명한 대로 터미널에서 pip 또는 conda를 사용하세요.

Positron

renv

renv를 사용한다면 Positron이 프로젝트 로컬 환경의 R 및/또는 Python 패키지에 Quarto를 자동으로 올바르게 연결합니다. R 패키지는 install.packages로, Python 패키지는 위에서 설명한 대로 터미널에서 pip 또는 conda로 설치하세요.

venv / condaenv

위에서 설명한 대로 venv 또는 conda로 가상 환경을 만들면 Positron이 상위 폴더를 열 때 해당 환경을 자동으로 발견합니다. 또한 Interpreter: Select Interpreter Session 명령으로 환경을 명시적으로 선택할 수 있습니다.

Quarto 실행 파일을 시스템 전체가 아닌 conda 환경에 설치했다면, Positron이 conda 설치 Quarto를 감지할 수 있도록 해당 conda 환경을 활성화한 터미널에서 Positron을 실행해야 합니다. Quarto 확장의 Quarto 경로 설정은 conda 환경에 설치된 Quarto에서는 동작하지 않습니다.

VS Code

위에서 설명한 대로 env/ 디렉터리에 venv 가상 환경을 만들면, Visual Studio Code가 환경 상위 디렉터리에서 워크스페이스를 로드할 때 해당 환경을 자동으로 발견합니다.

Visual Studio Code는 conda 환경도 자동으로 감지하지만, Python: Select Interpreter 명령으로 현재 세션에 연결해야 합니다.

Quarto 실행 파일을 시스템 전체가 아닌 conda 환경에 설치했다면, VSCode가 conda 설치 Quarto를 감지할 수 있도록 해당 conda 환경을 활성화한 터미널에서 VSCode를 실행해야 합니다. Quarto VSCode 확장의 Quarto 경로 설정은 conda 환경에 설치된 Quarto에서는 동작하지 않습니다.

VS Code의 Python 가상 환경 지원에 대해서는 https://code.visualstudio.com/docs/python/environments에서 더 알아볼 수 있습니다.