서문

모두가 uv의 빠른 속도를 홍보하고 있지만(UV: Python 패키지 관리의 신기원 - pip보다 100배 빠르다), 우리 연구실에서는 여러 머신 간에 Python 환경을 마이그레이션해야 하는 상황에서 uv로 환경을 재현하는 편리함도 주목할 만합니다.

동료들에게 uv 사용을 열심히 추천하고 있지만, 여전히 conda에 대한 의존도가 높고 새로운 도구를 시도하려 하지 않습니다.
그래서 결국 튜토리얼을 작성하여 uv 사용법을 소개하고, 연구실 환경 관리에 작은 변화를 일으키기로 했습니다.

uv 설치

공식 문서

Windows에서는 winget을 사용한 설치를 더 추천합니다:

Linux/macOS에서는 공식 문서를 참고하여 curl/wget으로 설치할 수 있습니다:

uv 환경 초기화

새 프로젝트를 초기화하려면 workspace 디렉토리에서 다음을 실행하세요:

또는 기존 Python 프로젝트를 uv 환경으로 마이그레이션하려면 프로젝트 디렉토리에서 다음을 실행하세요:

그러면 프로젝트 디렉토리에 다음과 같은 파일들이 생성됩니다:

1. .git, .gitignore, README.md는 설명이 필요 없습니다.
2. main.py는 예제 Python 파일이므로 필요 없으면 삭제해도 됩니다.
3. pyproject.toml은 Python 프로젝트의 설정 파일로, 프로젝트의 메타데이터와 의존성 정보를 기록합니다. 내용은 대략 다음과 같습니다: toml [project] name = "test-project" version = "0.1.0" description = "Add your description here" readme = "README.md" requires-python = ">=3.12" dependencies = []
4. .python-version은 현재 프로젝트의 Python 버전을 지정하는 데 사용됩니다.

Python 버전 지정

pyproject.toml 파일의 requires-python 필드를 편집하여 현재 프로젝트에 필요한 Python 버전을 지정합니다. 예: ==3.12, >=3.12 등.

그런 다음 다음 명령을 실행하여 지정된 버전의 Python을 설치합니다:

가상 환경 생성

이 명령은 현재 프로젝트 디렉토리에 .venv 폴더로 가상 환경을 생성합니다. 이후 출력 정보를 참고하여 가상 환경을 활성화할 수 있습니다. 예:

프로젝트 의존성 관리

기본 사용법

새로운 의존성을 설치하려면 다음 명령을 사용합니다:

사실상 기존의 pip install을 uv add로 대체하면 됩니다. 하지만 이 명령은 의존성을 가상 환경에 설치할 뿐만 아니라, 의존성 정보를 pyproject.toml 파일의 dependencies 필드에 자동으로 기록하고, 의존성 버전의 재현성을 보장하기 위해 uv.lock 잠금 파일을 업데이트합니다. uv.lock 파일은 수동으로 편집할 필요가 없지만 환경 재현에 매우 중요하므로 .gitignore에 추가하지 마세요.

예를 들어 requests를 설치하면 pyproject.toml에는 requests 의존성만 추가되지만, uv.lock에는 requests와 모든 하위 의존성의 구체적인 버전 정보가 상세히 기록됩니다. uv tree 명령으로 의존성 트리를 확인할 수 있습니다:

더 이상 필요하지 않은 의존성은 다음 명령으로 제거할 수 있습니다:

미러 소스

PyPI 미러 소스를 변경해야 한다면 pyproject.toml 파일에 다음 내용을 추가합니다 (NJU 미러를 예로 들면):

pip의 index-url

일부 패키지는 자체 PyPI 미러 소스에 배포됩니다. 예를 들어 torch의 pip 설치 명령(torch 공식 문서 참조)은 다음과 같습니다:

Using uv with PyTorch를 참고하여 다음 내용을 pyproject.toml 파일에 추가해야 합니다:

그렇지 않으면 CUDA 버전의 torch와 torchvision이 아닌 CPU 버전이 설치됩니다.

여기서는 먼저 pytorch-cu130이라는 인덱스 소스를 정의하고, url을 위 torch 문서에서 제공된 --index-url로 지정했지만, 여기서는 바로 NJU 미러 https://mirror.nju.edu.cn/pytorch/whl/cu130으로 대체했습니다.
그런 다음 tool.uv.sources에서 torch와 torchvision 패키지를 이 인덱스 소스에서 설치하도록 지정했습니다 (참고: marker는 운영 체제가 Linux 또는 Windows일 때만 pytorch-cu130 인덱스를 사용하도록 지정합니다. macOS 등 다른 운영 체제에서는 이 설정이 무시되고 기본 소스가 사용됩니다).

환경 재현

다른 머신에서 현재 프로젝트의 Python 환경을 재현해야 할 때는 프로젝트 코드를 클론한 후 다음 명령을 실행하면 됩니다:

다른 프로젝트에서 동일한 환경을 재현하려면 pyproject.toml, uv.lock, .python-version 파일을 대상 프로젝트 디렉토리로 복사하고, pyproject.toml의 프로젝트 정보를 업데이트한 후 동일한 명령을 실행합니다:

패키지 빌드 및 배포

다른 사람이 설치할 수 있는 PyPI 패키지를 작성 중이라면, 어떤 의존성이 개발 의존성이고 어떤 것이 런타임 의존성인지 고려해야 합니다. 개발 의존성은 uv add --dev [package-name] 명령으로 설치합니다.

그런 다음 pyproject.toml 파일에 저자, 라이선스, 빌드 정보 등 프로젝트 정보를 추가해야 합니다. 연구를 하는 경우 대부분 패키지를 배포하지 않으므로 여기서는 자세히 다루지 않겠습니다. 아래 내용을 참고하여 이해할 수 있습니다:

그런 다음 다음 명령으로 패키지를 빌드하고 배포할 수 있습니다:

기타 유용한 명령

1. uv cache clear: uv 캐시를 삭제하여 디스크 공간을 확보합니다.
2. uv tree: 현재 프로젝트의 의존성 트리를 확인합니다.
3. uv run main.py: 가상 환경을 활성화한 후 python main.py를 실행하는 것과 같으며, 프로젝트의 Python 스크립트를 실행하는 데 사용할 수 있습니다.
4. uvx [script-name]: 도구를 실행합니다. 일부 Python 패키지는 명령줄 도구를 제공하며, uvx 명령으로 실행할 수 있습니다. 예: uvx NJUlogin -h.