uv와 Jupyter 함께 사용하기
Jupyter 노트북은 대화형 컴퓨팅, 데이터 분석 및 시각화를 위한 인기 있는 도구입니다. uv와 함께 Jupyter를 여러 가지 방법으로 사용할 수 있으며, 프로젝트와 상호 작용하거나 독립 실행형 도구로 활용할 수 있습니다.
프로젝트 내에서 Jupyter 사용하기
프로젝트 내에서 작업하는 경우, 다음과 같이 프로젝트의 가상 환경에 접근 권한을 가진 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을 개발 의존성으로 설치해야 합니다:
# ipykernel을 개발 의존성으로 추가
$ uv add --dev ipykernel
그런 다음 프로젝트용 커널을 다음과 같이 생성할 수 있습니다:
# 'project'라는 이름으로 사용자 레벨 커널 생성
# VIRTUAL_ENV 환경 변수를 사용하여 현재 가상 환경 경로 지정
$ uv run ipython kernel install --user --env VIRTUAL_ENV $(pwd)/.venv --name=project
이후 다음과 같이 서버를 시작합니다:
# Jupyter Lab 서버 시작 (격리된 환경 사용)
$ uv run --with jupyter jupyter lab
커널 사용하기
노트북을 생성할 때 드롭다운에서 프로젝트 커널을 선택합니다. 그런 다음 !uv add pydantic을 사용하여 pydantic을 프로젝트의 의존성에 추가하거나, !uv pip install pydantic을 사용하여 프로젝트의 pyproject.toml 또는 uv.lock 파일에 변경 사항을 유지하지 않고 프로젝트의 가상 환경에 pydantic을 설치할 수 있습니다. 두 명령 모두 노트북 내에서 import pydantic이 작동하게 합니다.
커널 생성
ipykernel 설치 및 커널 등록
서버 시작
Jupyter Lab 실행
커널 선택
노트북에서 프로젝트 커널 선택
패키지 설치
!uv add 또는
!uv pip install 사용
커널 없이 패키지 설치하기
커널을 만들고 싶지 않다면 노트북 내에서도 패키지를 설치할 수 있습니다. 그러나 고려해야 할 몇 가지 주의사항이 있습니다.
uv run --with jupyter가 격리된 환경에서 실행되더라도, 노트북 내에서 !uv add 및 관련 명령은 커널 없이도 프로젝트의 환경을 수정합니다.
예를 들어, 노트북 내에서 !uv add pydantic을 실행하면 pydantic이 프로젝트의 의존성 및 가상 환경에 추가되어 추가 구성이나 서버 재시작 없이 import pydantic이 즉시 작동합니다.
!uv add 명령 사용
  • 프로젝트의 의존성에 패키지 추가
  • 프로젝트의 가상 환경에 패키지 설치
  • pyproject.toml 및 uv.lock 파일 업데이트
!uv pip install 명령 사용
  • Jupyter 환경에 패키지 설치 (주의!)
  • Jupyter 서버 수명 동안만 유지
  • 프로젝트 파일 업데이트 없음
Jupyter 환경과 프로젝트 환경의 차이
그러나 Jupyter 서버가 "활성" 환경이기 때문에 !uv pip install은 프로젝트 환경이 아닌 Jupyter의 환경에 패키지를 설치합니다. 이러한 의존성은 Jupyter 서버 수명 동안 유지되지만 이후 jupyter 호출 시 사라질 수 있습니다.
pip에 의존하는 노트북(예: %pip 매직을 통해)으로 작업하는 경우, Jupyter 서버를 시작하기 전에 uv venv --seed를 실행하여 프로젝트의 가상 환경에 pip를 포함할 수 있습니다. 예를 들어:
# 가상 환경 생성 시 pip 포함 (--seed 옵션 사용)
$ uv venv --seed
# Jupyter Lab 서버 시작
$ uv run --with jupyter jupyter lab
pip 매직 사용하기
이후 노트북 내에서 %pip install 호출은 프로젝트의 가상 환경에 패키지를 설치합니다. 그러나 이러한 수정 사항은 프로젝트의 pyproject.toml 또는 uv.lock 파일에 반영되지 않습니다.
%pip 매직 사용
노트북 내에서 직접 pip 명령어 실행 가능
주의사항
프로젝트 파일에는 변경사항이 반영되지 않음
사전 준비
--seed 옵션으로 pip 포함 필요
독립 실행형 도구로 Jupyter 사용하기
노트북에 임시 액세스가 필요한 경우(예: Python 스니펫을 대화식으로 실행하기 위해) uv tool run jupyter lab으로 언제든지 Jupyter 서버를 시작할 수 있습니다. 이렇게 하면 격리된 환경에서 Jupyter 서버가 실행됩니다.
장점
  • 빠른 설정
  • 프로젝트와 독립적
  • 임시 작업에 이상적
  • 격리된 환경 제공
사용 사례
  • 코드 스니펫 테스트
  • 빠른 데이터 탐색
  • 개념 증명 작업
  • 일회성 분석
# 격리된 환경에서 Jupyter 서버 시작
$ uv tool run jupyter lab
비 프로젝트 환경에서 Jupyter 사용하기
프로젝트와 연결되지 않은 가상 환경(예: pyproject.toml 또는 uv.lock이 없는)에서 Jupyter를 실행해야 하는 경우, 환경에 직접 Jupyter를 추가하여 실행할 수 있습니다. 예를 들어:
macOS 및 Linux
# 가상 환경 생성 (pip 포함)
$ uv venv --seed
# pydantic 설치
$ uv pip install pydantic
# jupyterlab 설치
$ uv pip install jupyterlab
# Jupyter Lab 실행 (가상 환경 내 실행 파일 직접 사용)
$ .venv/bin/jupyter lab
Windows
# 가상 환경 생성 (pip 포함)
$ uv venv --seed
# pydantic 설치
$ uv pip install pydantic
# jupyterlab 설치
$ uv pip install jupyterlab
# Jupyter Lab 실행 (가상 환경 내 실행 파일 직접 사용)
$ .venv\Scripts\jupyter lab
비 프로젝트 환경에서의 패키지 관리
이렇게 설정하면 노트북 내에서 import pydantic이 작동하며, !uv pip install 또는 !pip install을 통해 추가 패키지를 설치할 수 있습니다.
가상 환경 생성
uv venv --seed 명령으로 pip를 포함한 가상 환경을 생성합니다.
기본 패키지 설치
uv pip install을 사용하여 필요한 기본 패키지(pydantic, jupyterlab 등)를 설치합니다.
Jupyter 실행
가상 환경 내의 jupyter 실행 파일을 직접 호출하여 Jupyter Lab을 시작합니다.
추가 패키지 설치
노트북 내에서 !uv pip install 또는 !pip install을 사용하여 필요한 추가 패키지를 설치합니다.
VS Code에서 Jupyter 사용하기
VS Code와 같은 에디터 내에서도 Jupyter 노트북을 사용할 수 있습니다. VS Code 내에서 uv로 관리되는 프로젝트를 Jupyter 노트북에 연결하려면 다음과 같이 프로젝트용 커널을 만드는 것이 좋습니다:
# 새 프로젝트 생성
$ uv init
# 프로젝트 디렉토리로 이동
$ cd project
# ipykernel을 개발 의존성으로 추가
$ uv add --dev ipykernel
# VS Code에서 프로젝트 열기
$ code .
VS Code에서 Jupyter 노트북 생성하기
VS Code에서 프로젝트 디렉토리가 열리면 명령 팔레트에서 "Create: New Jupyter Notebook"을 선택하여 새 Jupyter 노트북을 만들 수 있습니다. 커널 선택 메시지가 표시되면 "Python Environments"를 선택하고 이전에 만든 가상 환경(예: macOS 및 Linux의 경우 .venv/bin/python, Windows의 경우 .venv\Scripts\python)을 선택합니다.
VS Code 열기
프로젝트 디렉토리에서 VS Code 실행
명령 팔레트 열기
Ctrl+Shift+P (Windows/Linux) 또는 Cmd+Shift+P (Mac)
새 노트북 생성
"Create: New Jupyter Notebook" 선택
커널 선택
프로젝트 가상 환경 선택
VS Code에서의 ipykernel 요구사항
VS Code는 프로젝트 환경에 ipykernel이 있어야 합니다. ipykernel을 개발 의존성으로 추가하지 않으려면 uv pip install ipykernel을 사용하여 프로젝트 환경에 직접 설치할 수 있습니다.
VS Code는 프로젝트 환경에 ipykernel이 있어야 합니다. ipykernel을 개발 의존성으로 추가하지 않으려면 uv pip install ipykernel을 사용하여 프로젝트 환경에 직접 설치할 수 있습니다.
노트북 내에서 프로젝트의 환경을 조작해야 하는 경우 uv를 명시적인 개발 의존성으로 추가해야 할 수 있습니다:
# uv를 개발 의존성으로 추가 (노트북 내에서 uv 명령어 사용 위함)
$ uv add --dev uv
VS Code 노트북에서 패키지 관리하기
이후에는 !uv add pydantic을 사용하여 pydantic을 프로젝트의 의존성에 추가하거나, !uv pip install pydantic을 사용하여 프로젝트의 pyproject.toml 또는 uv.lock 파일을 업데이트하지 않고 프로젝트의 가상 환경에 pydantic을 설치할 수 있습니다.
의존성 추가 방법
# 노트북 셀 내에서 실행
!uv add pydantic
이 방법은 패키지를 프로젝트의 의존성으로 추가하고 pyproject.toml 및 uv.lock 파일을 업데이트합니다.
임시 설치 방법
# 노트북 셀 내에서 실행
!uv pip install pydantic
이 방법은 프로젝트 파일을 업데이트하지 않고 가상 환경에만 패키지를 설치합니다.