이 글은 WSL 환경에서 uv로 파이썬 개발 환경을 세팅하는 방법에 대해 정리한 글입니다.
이모저모...
파이썬 개발 환경을 세팅하면서 고민한 점은 3가지이다.
- 여러 파이썬 버전을 쉽게 설치하고 관리할 수 있어야 한다.
- 프로젝트 별 가상환경을 빠르게 만들고 유지할 수 있어야 한다.
- VS Code Remote 환경에서 자연스럽게 연결되어야 한다.
위 3가지 고민한 부분에 적합한 것은 uv라고 생각했다. 기존에는 pyenv + venv 조합이 자주 사용되었지만, uv는 파이썬 설치, 가상환경 구성, 패키지 관리까지 한 흐름으로 다룰 수 있어서 세팅과 운영이 더 단순하다고 판단했다. uv가 익숙한 환경은 아니지만, 파이썬 설치와 프로젝트 환경 관리, 패키지 관리, 워크스페이스 구성까지 한 번에 다룰 수 있다는 점에서 매력적인 환경으로 다가왔다.
최종적으로 구성하고자 하는 환경은 다음과 같다.
- OS : Windows 11 WSL Ubuntu 24.04
- IDE : Visual Studio Code + Remote WSL
- Python : uv
uv 설치
그럼 본격적으로 uv를 설치해보자.
curl -LsSf https://astral.sh/uv/install.sh | sh설치가 완료되었으면 터미널을 다시 시작하거나 쉘 설정 파일(~/.bashrc, ~/.zshrc)을 다시 시작한다.
source ~/.bashrc
# 또는
source ~/.zshrc그리고 아래 명령어로 제대로 설치되었는지 확인한다. 버전이 출력되면 정상적으로 설치된 것이다. (2026.04.07. 기준 0.11.3 버전)
uv --version파이썬 설치
uv를 사용해서 다양한 버전의 파이썬을 설치할 수 있다. 아래 명령어로 현재 설치되어 있는 파이썬 버전과 경로를 확인할 수 있다.
uv python list특정 버전의 파이썬을 설치하려면 아래와 같이 설치할 수 있다.
# uv python install <version>
uv python install 3.10여러 버전을 한 번에 설치하려면, 아래와 같이 사용할 수 있다.
uv python install 3.10 3.11 3.12프로젝트 시작
uv는 프로젝트 초기화 작업도 지원한다. 프로젝트 디렉토리에서 아래 명령어를 통해 프로젝트 초기화를 진행할 수 있다.
uv init초기화 후에 생성되는 pyproject.toml에서 파이썬 버전을 명시할 수 있으며, 의존성 등을 관리할 수 있다.
아래 명령어를 통해 프로젝트에 필요한 가상환경과 의존성 구성이 맞춰진다.
uv sync또한 필요한 패키지는 아래 명령어로 추가할 수 있다.
uv add requests자주 사용하는 uv 명령어
# uv 설치 확인
uv --version
# uv 실행 파일 경로 확인
which uv
# 설치 가능한/설치된 파이썬 확인
uv python list
# 특정 파이썬 버전 설치
uv python install 3.10
# 여러 파이썬 버전 한 번에 설치
uv python install 3.10 3.11 3.12
# 특정 파이썬 버전 삭제
uv python uninstall 3.10
# 프로젝트 초기화
uv init
# 프로젝트 환경 동기화
uv sync
# 패키지 추가
uv add requests
# 개발용 패키지 추가
uv add --dev pytest