Skip to content

Jupyter에서 uv 사용하기

Jupyter 노트북은 인터랙티브 컴퓨팅, 데이터 분석, 시각화에 널리 사용되는 도구다. Jupyter와 uv를 함께 사용하는 방법은 여러 가지가 있다. 프로젝트와 상호작용하거나 독립적인 도구로 활용할 수 있다.

프로젝트 내에서 Jupyter 사용하기

프로젝트 내에서 작업 중이라면, 다음 명령어를 통해 프로젝트의 가상 환경에 접근할 수 있는 Jupyter 서버를 시작할 수 있다:

$ uv run --with jupyter jupyter lab

기본적으로 jupyter lab은 http://localhost:8888/lab에서 서버를 시작한다.

노트북 내에서는 프로젝트의 모듈을 프로젝트의 다른 파일에서와 동일하게 임포트할 수 있다. 예를 들어, 프로젝트가 requests에 의존한다면, import requests는 프로젝트의 가상 환경에서 requests를 임포트한다.

프로젝트의 가상 환경에 읽기 전용으로 접근하려면 별도의 작업이 필요하지 않다. 하지만 노트북 내에서 추가 패키지를 설치해야 한다면 몇 가지 추가적인 사항을 고려해야 한다.

커널 생성하기

노트북 내부에서 패키지를 설치해야 한다면, 프로젝트 전용 커널을 생성하는 것을 권장한다. 커널은 Jupyter 서버가 하나의 환경에서 실행되도록 하면서, 개별 노트북이 각각의 독립된 환경에서 실행되게 한다.

uv 환경에서는 Jupyter 자체를 격리된 환경에 설치하면서 프로젝트용 커널을 생성할 수 있다. 예를 들어 uv run --with jupyter jupyter lab 명령어를 사용하면 된다. 프로젝트용 커널을 생성하면 노트북이 올바른 환경에 연결되고, 노트북 내부에서 설치한 패키지가 프로젝트의 가상 환경에 설치된다.

커널을 생성하려면 ipykernel을 개발 의존성으로 설치해야 한다:

$ uv add --dev ipykernel

그런 다음, project용 커널을 생성할 수 있다:

$ uv run ipython kernel install --user --env VIRTUAL_ENV $(pwd)/.venv --name=project

이후 서버를 시작한다:

$ uv run --with jupyter jupyter lab

노트북을 생성할 때 드롭다운 메뉴에서 project 커널을 선택한다. 그런 다음 !uv add pydantic 명령어를 사용해 프로젝트 의존성에 pydantic을 추가하거나, !uv pip install pydantic 명령어를 사용해 프로젝트의 가상 환경에 pydantic을 설치할 수 있다. 후자의 경우 프로젝트 pyproject.toml이나 uv.lock 파일에 변경 사항이 저장되지 않는다. 두 명령어 모두 노트북 내에서 import pydantic이 동작하도록 한다.

커널 없이 패키지 설치하기

커널을 생성하지 않고도 노트북 내에서 패키지를 설치할 수 있다. 하지만 몇 가지 주의할 점이 있다.

uv run --with jupyter 명령어는 격리된 환경에서 실행되지만, 노트북 내에서 !uv add와 관련 명령어를 사용하면 커널 없이도 프로젝트 환경을 수정한다.

예를 들어, 노트북에서 !uv add pydantic을 실행하면 pydantic이 프로젝트의 의존성과 가상 환경에 추가된다. 이 경우, import pydantic을 바로 사용할 수 있으며, 추가 설정이나 서버 재시작이 필요 없다.

하지만 Jupyter 서버가 '활성' 환경이기 때문에 !uv pip install 명령어는 프로젝트 환경이 아닌 Jupyter 환경에 패키지를 설치한다. 이러한 의존성은 Jupyter 서버가 실행 중인 동안 유지되지만, 이후 jupyter를 다시 실행할 때 사라질 수 있다.

만약 %pip 매직 명령어를 사용하는 노트북에서 작업한다면, Jupyter 서버를 시작하기 전에 uv venv --seed를 실행해 프로젝트의 가상 환경에 pip를 포함시킬 수 있다. 예를 들어:

$ uv venv --seed
$ uv run --with jupyter jupyter lab

이후 노트북 내에서 %pip install 명령어를 실행하면 패키지가 프로젝트의 가상 환경에 설치된다. 하지만 이러한 변경 사항은 프로젝트의 pyproject.toml이나 uv.lock 파일에 반영되지 않는다.

Jupyter를 독립 실행형 도구로 사용하기

특정 시점에 노트북에 임시로 접근해야 하는 경우(예: 대화형으로 Python 코드 조각을 실행하기 위해), uv tool run jupyter lab 명령어를 사용해 언제든지 Jupyter 서버를 시작할 수 있다. 이 명령어는 Jupyter 서버를 독립된 환경에서 실행한다.

프로젝트 환경 없이 Jupyter 사용하기

프로젝트와 연결되지 않은 가상 환경에서 Jupyter를 실행해야 하는 경우(예: pyproject.toml이나 uv.lock 파일이 없는 경우), Jupyter를 직접 환경에 추가할 수 있다. 예를 들어:

=== "macOS와 Linux"

```console
$ uv venv --seed
$ uv pip install pydantic
$ uv pip install jupyterlab
$ .venv/bin/jupyter lab
```

=== "Windows"

```powershell
uv venv --seed
uv pip install pydantic
uv pip install jupyterlab
.venv\Scripts\jupyter lab
```

이제 노트북 내에서 import pydantic이 작동하며, 추가 패키지를 !uv pip install 또는 !pip install로 설치할 수 있다.

VS Code에서 Jupyter 사용하기

VS Code와 같은 편집기에서도 Jupyter 노트북을 사용할 수 있다. uv로 관리되는 프로젝트를 VS Code 내의 Jupyter 노트북에 연결하려면, 다음과 같이 프로젝트용 커널을 생성하는 것을 추천한다:

# 프로젝트 생성
$ uv init project

# 프로젝트 디렉토리로 이동
$ cd project

# 개발 의존성으로 ipykernel 추가
$ uv add --dev ipykernel

# VS Code에서 프로젝트 열기
$ code .

VS Code에서 프로젝트 디렉토리를 연 후, 커맨드 팔레트에서 "Create: New Jupyter Notebook"을 선택해 새로운 Jupyter 노트북을 생성할 수 있다. 커널을 선택하라는 메시지가 표시되면 "Python Environments"를 선택하고 앞서 생성한 가상 환경(예: macOS와 Linux에서는 .venv/bin/python, Windows에서는 .venv\Scripts\python)을 선택한다.

Note

VS Code는 프로젝트 환경에 ipykernel이 설치되어 있어야 한다. ipykernel을 개발 의존성으로 추가하고 싶지 않다면, uv pip install ipykernel을 사용해 프로젝트 환경에 직접 설치할 수 있다.

노트북 내에서 프로젝트 환경을 조작해야 한다면, uv를 명시적인 개발 의존성으로 추가해야 할 수도 있다:

$ uv add --dev uv

이후 !uv add pydantic을 사용해 프로젝트의 의존성에 pydantic을 추가하거나, !uv pip install pydantic을 사용해 프로젝트의 가상 환경에 pydantic을 설치할 수 있다. 이때 프로젝트의 pyproject.toml이나 uv.lock 파일은 업데이트되지 않는다.