Python. uv 를 사용한 Jupyter Notebook 운용

기본 구성

프로젝트가 있다고 가정합니다.

uv init --python 3.12 my-project
cd my-project

필요한 패키지는 uv로 프로젝트에 추가합니다.

uv add pandas numpy matplotlib

Jupyter kernel용으로 ipykernel을 dev dependency로 추가합니다.

uv add --dev ipykernel

그 다음 Jupyter Lab을 실행합니다.

uv run --with jupyter jupyter lab

uv run --with jupyter jupyter lab은 Jupyter 자체를 별도 환경에서 실행하면서도, 프로젝트의 가상환경을 사용할 수 있게 해줍니다. (Astral Docs)

기본 구성된 프로젝트를 VS Code 에서 작업할 경우

VS Code에서 노트북을 만들고 커널 선택할 때:

Python Environments → .venv/bin/python

Windows라면:

.venv\Scripts\python

을 고르면 됩니다.

패키지를 추가할 때의 기준

노트북에서 실험하다가 패키지가 필요해졌다면, 가능하면 터미널에서:

uv add seaborn

또는 노트북 셀에서:

!uv add seaborn

을 쓰세요.

이렇게 하면 pyproject.toml과 uv.lock에 기록됩니다. 즉, 나중에 다른 컴퓨터나 팀원이 실행해도 같은 환경을 재현할 수 있습니다.

요약

uv + Jupyter 베스트 프랙티스는 다음과 같습니다.

uv init
uv add 필요한_패키지들
uv add --dev ipykernel
uv run --with jupyter jupyter lab

VS Code에서는 .venv의 Python을 커널로 선택하세요.

패키지 추가는 기본적으로 uv add 로 하면 됩니다.