프로젝트 구조와 파일

pyproject.toml

Python 프로젝트 메타데이터는 pyproject.toml 파일에 저장됩니다. uv는 이 파일을 사용하여 프로젝트의 루트 디렉터리를 인식합니다.

기본 프로젝트에는 이름과 버전만 필요합니다:

[project]
name = "example"
version = "0.1.0"

추가 설정에는 Python 버전 요구사항, 의존성(dependency), 빌드 시스템, 엔트리 포인트 등이 포함될 수 있습니다.

프로젝트 환경(Project Environment)

uv로 개발할 때, 가상환경(virtual environment)은 pyproject.toml과 함께 .venv 디렉터리에 자동으로 생성됩니다. 이 위치는 편집기가 코드 자동완성 및 타입 힌트를 위해 환경을 찾는 데 도움이 됩니다. .venv 폴더는 버전 관리에 커밋하지 않아야 합니다. 내부 .gitignore를 통해 자동으로 제외됩니다.

프로젝트 환경 내에서 명령어를 실행하려면 uv run을 사용합니다. 환경은 필요에 따라 생성되거나 업데이트됩니다. 명시적으로 생성하려면 uv sync를 사용합니다.

중요: 프로젝트 환경을 직접 편집하지 마십시오. 프로젝트 의존성에는 uv add를, 임시 요구사항에는 uvx 또는 uv run --with를 사용하십시오.

pyproject.toml에서 managed = false를 설정하면 자동 관리를 비활성화할 수 있습니다:

[tool.uv]
managed = false

락파일(Lockfile)

uv는 pyproject.toml과 함께 uv.lock 파일을 생성합니다. 이 범용 락파일(lockfile)은 운영 체제, 아키텍처, Python 버전 등 모든 Python 환경에 걸쳐 정확한 패키지 버전을 기록합니다.

pyproject.toml이 넓은 범위의 요구사항을 지정하는 반면, 락파일은 실제로 설치되는 내용을 정확히 기록합니다. 이를 통해 서로 다른 머신 간 재현 가능한 빌드와 일관된 배포가 가능합니다. 락파일은 버전 관리에 포함해야 합니다.

락파일은 uv sync 및 uv run 명령어 실행 시 자동으로 업데이트되며, uv lock을 통해 명시적으로 업데이트할 수도 있습니다. 사람이 읽을 수 있는 TOML 형식이지만, uv가 관리하므로 직접 편집하지 않아야 합니다.

pylock.toml과의 관계

PEP 751은 requirements.txt를 대체하는 pylock.toml을 표준화했습니다. 이 형식은 미래의 상호운용성을 위해 도구 독립적(tool-agnostic)입니다.

일부 uv 기능은 pylock.toml로 표현할 수 없으므로, uv는 프로젝트에 uv.lock 형식을 계속 사용합니다. 다만 uv는 pylock.toml로의 내보내기(export)를 지원합니다:

• 내보내기: uv export -o pylock.toml
• 요구사항에서 생성: uv pip compile requirements.in -o pylock.toml
• 설치: uv pip sync pylock.toml 또는 uv pip install -r pylock.toml

원문(영어): https://docs.astral.sh/uv/concepts/projects/layout/ · 본 문서는 학습용 한국어 번역이며 원본의 권리는 원저작자(Astral)에게 있습니다.

원문(영어): https://docs.astral.sh/uv/concepts/projects/layout/