python 가상 개발환경 사용하기 (feat uv)

Background

python의 생태계는 거대하지만 package 관리나 개발환경 쪽에서는 의외로 불편함이 있다. 근래에 asdf와 poetry를 알게 되어 정착하게 되었다. 이에 대해서는 “의외의 복병 개발환경, asdf로 개발 언어를 관리해 보자“와 “python 가상 개발환경 사용하기 (feat poetry)“를 참고하자.

최근 uv라는 tool을 알게 되었다. 가상환경, project, package를 모두 함께 관리해준다는 점에서 poetry와 유사하다. javascript의 npm, ruby의 bundle, python의 poetry를 사용해 보았다면 uv를 익히는데 어려움이 없을 것이다.

poetry와 비교했을 때 uv의 장점은 속도에 있다. package 설치와 관리가 매우 빠른 속도로 수행된다. 아울러 python version을 설치하고 관리할 수 있다는 점도 poetry와 다른 점이다.

Install

설치. 내용이 조금씩 바뀌므로 현재 시점에서 가장 정확한 내용은 공식 문서를 참고하자.

설치는 공식 installer를 사용한다. 설치 방법은 아래와 같다.

curl -LsSf https://astral.sh/uv/install.sh | sh

설치 확인

uv --version

Commands

기본적인 사용방법을 정리한다. 자세한 내용은 공식 홈페이지를 참고하자.

# 새로운 프로젝트 생성
uv init my-project
cd my-project

# 기존 프로젝트가 이미 있다면 
# cd my-project
# uv init

# package 추가
uv add numpy
# package 추가
# uv remove numpy

# uv.lock file 생성
uv lock

# uv.lock file과 현재 환경 동기화
uv sync

package 설치와 제거 과정에서 문제가 있다면 가상 환경 속에서 실행해서일 가능성이 있다. 이럴 때는 deactivate를 이용하여 가상 환경에서 나온 뒤에 다시 해보자.

# excute script within env
# poetry: poetry run python your_script.py
uv run your_script.py

python version을 지정하거나 따로 설치할 수 있다는 점이 유용하다.

# 가상환경에서 사용할 python 버전을 지정
# 시스템에 있으면 해당 python과 연결하고, 없다면 새로 설치한다. 
# `.python-version` file이 생성된다.
uv venv --python 3.11.6

#To install a Python version
uv python install 3.12

# To list installed and available Python versions:
uv python list

# To find a Python executable, use the uv python find command:
uv python find

Tips

Custom package 사용

때때로 uv project 안에서 자신이 만든 custom package를 사용하고 싶을 때가 있다. 예를 들어 폴더 구조가 다음과 같을 때,

.
├── my-package
│   ├── foo/
│   │   ├──__init__.py
│   │   └── a.py
│   └── bar/
│       ├── __init__.py
│       └── b.py
……

아래와 같이 사용하고 싶다면 어떻게 해야 할까?

# ./my-package/bar/b.py
from foo import a

poetry의 경우에는 설정 파일인 pyproject.toml에 다음과 같이 적어 주고 poetry install을 실행시켜주면 된다.

# pyproject.toml
[tool.poetry.dependencies]
foo = { path = "./my-package/foo" }
bar = { path = "./my-package/bar" }

uv의 경우에는 이런 경우를 위한 방법이 정확히 제시되어 있지 않다. 몇가지 시도해 볼 수 있는 방법은 다음과 같다. 아직 정확한 방법은 모르겠다.

pyproject.toml을 수정한 뒤에는 uv sync를 실행하자.

# pyproject.toml
[tool.uv.workspace]
members = ["."]
include = ["my-package/foo", "my-package/bar"]
# exclude = ["my-package/seeds"]

또는

# pyproject.toml
[tool.setuptools.packages.find]
where = ["."]
include = ["my-package/foo", "my-package/bar"]
# exclude = ["my-package/seeds"]

또는

# pyproject.toml
# `my-package`가 `src`로 되어 있어야 한다. 
[tool.uv]
package = true

[tool.setuptools]
packages = ["foo", "bar"]
... ... ... ...
Back