프로젝트 구조와 파일¶
pyproject.toml 파일¶
파이썬 프로젝트의 메타데이터는 pyproject.toml 파일에 정의된다. uv는 이 파일을 통해 프로젝트의 루트 디렉토리를 식별한다.
Tip
uv init 명령어를 사용해 새로운 프로젝트를 생성할 수 있다. 자세한 내용은 프로젝트 생성을 참고한다.
최소한의 프로젝트 정의는 이름과 버전을 포함한다:
[project]
name = "example"
version = "0.1.0"
추가적인 프로젝트 메타데이터와 설정은 다음과 같다:
프로젝트 환경¶
uv로 프로젝트를 작업할 때, uv는 필요에 따라 가상 환경을 생성한다. 일부 uv 커맨드는 임시 환경을 생성하기도 하지만(예: uv run --isolated), uv는 프로젝트와 그 의존성을 .venv 디렉토리에 저장해 지속적인 환경을 관리한다. 이 디렉토리는 pyproject.toml 파일 옆에 위치하며, 에디터가 코드 완성과 타입 힌트를 제공하기 위해 환경을 쉽게 찾을 수 있도록 프로젝트 내부에 저장된다. .venv 디렉토리는 버전 관리에 포함하지 않는 것이 좋다. uv는 내부 .gitignore 파일을 통해 자동으로 git에서 제외한다.
프로젝트 환경에서 커맨드를 실행하려면 uv run을 사용한다. 또는 일반적인 가상 환경처럼 프로젝트 환경을 활성화할 수도 있다.
uv run을 실행하면 프로젝트 환경이 아직 존재하지 않을 경우 생성하고, 이미 존재할 경우 최신 상태로 유지한다. 프로젝트 환경은 uv sync를 통해 명시적으로 생성할 수도 있다.
uv pip install과 같은 방법으로 프로젝트 환경을 수동으로 수정하는 것은 권장하지 않는다. 프로젝트 의존성을 추가하려면 uv add를 사용해 패키지를 환경에 추가한다. 일회성 요구 사항은 uvx 또는 uv run --with를 사용한다.
Tip
uv가 프로젝트 환경을 관리하지 않도록 하려면 managed = false를 설정해 자동 잠금 및 동기화를 비활성화한다. 예를 들어:
[tool.uv]
managed = false
락 파일¶
uv는 pyproject.toml 파일 옆에 uv.lock 파일을 생성한다.
uv.lock은 운영체제, 아키텍처, 파이썬 버전 등 모든 가능한 파이썬 마커를 고려해 설치될 패키지를 기록하는 범용 또는 크로스 플랫폼 락 파일이다.
프로젝트의 광범위한 요구 사항을 지정하는 데 사용되는 pyproject.toml과 달리, 락 파일은 프로젝트 환경에 설치된 정확한 버전 정보를 포함한다. 이 파일은 버전 관리 시스템에 체크인해야 하며, 이를 통해 여러 머신에서 일관되고 재현 가능한 설치를 보장한다.
락 파일은 프로젝트를 작업하는 개발자들이 일관된 패키지 버전을 사용하도록 한다. 또한, 애플리케이션으로 프로젝트를 배포할 때 사용된 정확한 패키지 버전 집합을 알 수 있게 한다.
락 파일은 프로젝트 환경을 사용하는 uv 명령어, 즉 uv sync와 uv run을 실행할 때 생성되고 업데이트된다. 또한 uv lock 명령어를 사용해 명시적으로 업데이트할 수도 있다.
uv.lock은 사람이 읽을 수 있는 TOML 파일이지만, uv에 의해 관리되며 수동으로 편집하면 안 된다. 현재 파이썬 표준 락 파일 형식은 없기 때문에, 이 파일의 형식은 uv에 특화되어 있으며 다른 도구에서는 사용할 수 없다.