프로젝트 설정

Python 버전 요구사항

프로젝트는 pyproject.toml의 project.requires-python 필드를 통해 지원하는 Python 버전을 지정할 수 있습니다. 이 선언은 허용되는 Python 문법을 결정하고 의존성 버전 선택에 영향을 미칩니다.

[project]
name = "example"
version = "0.1.0"
requires-python = ">=3.12"

엔트리 포인트(Entry points)

엔트리 포인트는 패키지가 명령줄 도구, 그래픽 애플리케이션, 플러그인 검색 시스템 등의 인터페이스를 알릴 수 있도록 합니다.

중요: 엔트리 포인트 테이블에는 빌드 시스템 정의가 필요합니다.

명령줄 인터페이스(Command-line interfaces)

[project.scripts] 테이블을 사용하여 CLI를 정의합니다:

[project.scripts]
hello = "example:hello"

그런 다음 uv run hello로 실행합니다.

그래픽 사용자 인터페이스(Graphical user interfaces)

[project.gui-scripts]를 통해 GUI를 정의합니다:

[project.gui-scripts]
hello = "example:app"

Windows에서는 콘솔 창 없이 실행됩니다. 다른 플랫폼에서는 CLI와 동일하게 취급됩니다.

플러그인 엔트리 포인트(Plugin entry points)

[project.entry-points]를 사용하여 플러그인을 등록합니다:

[project.entry-points.'example.plugins']
a = "example_plugin_a"

코드에서 플러그인을 로드합니다:

from importlib.metadata import entry_points

for plugin in entry_points(group='example.plugins'):
    plugin.load()

충돌을 방지하기 위해 패키지 이름으로 그룹 키를 네임스페이스화합니다.

빌드 시스템(Build systems)

빌드 시스템은 프로젝트를 패키징하고 설치하는 방법을 결정합니다. [build-system] 테이블에 정의합니다. uv는 이 테이블의 존재 여부로 프로젝트 자체를 빌드하고 설치할지 여부를 결정합니다.

빌드 시스템이 없으면 uv는 의존성만 설치합니다. 있으면 프로젝트를 빌드하고 환경에 설치합니다.

빌드 시스템은 다음을 지원합니다: - 배포에 포함하거나 제외할 파일 지정 - 편집 가능 설치 구성 - 동적 프로젝트 메타데이터 - 네이티브 코드 컴파일 - 공유 라이브러리 벤더링

uv init --build-backend 또는 uv init --package를 사용하여 패키지형 프로젝트를 만들 수 있습니다.

프로젝트 패키징(Project packaging)

다음이 필요한 경우 프로젝트를 패키징합니다: - 명령줄 도구 추가 - 다른 사용자에게 배포 - src 및 test 레이아웃 사용 - 라이브러리 작성

다음의 경우 패키징을 건너뜁니다: - 스크립트 작성 - 간단한 애플리케이션 빌드 - 플랫 레이아웃 사용

tool.uv.package 설정으로 자동 감지를 재정의합니다:

[tool.uv]
package = true   # 강제 패키징
# 또는
package = false  # 패키징 방지

프로젝트 환경 경로(Project environment path)

UV_PROJECT_ENVIRONMENT 변수를 사용하여 가상환경 경로를 설정합니다(기본값: .venv).

상대 경로는 워크스페이스 루트에서 해석됩니다. 절대 경로는 그대로 사용됩니다. 환경이 존재하지 않으면 uv가 생성합니다.

Debian에서 시스템 Python을 대상으로 하는 예:

$ python -c "import sysconfig; print(sysconfig.get_config_var('prefix'))"
/usr/local
$ export UV_PROJECT_ENVIRONMENT=/usr/local

중요: 여러 프로젝트에서 절대 경로를 사용하면 환경을 덮어씁니다. 이 설정은 단일 프로젝트 CI 또는 Docker 시나리오에만 적합합니다.

참고: uv는 프로젝트 작업 중 기본적으로 VIRTUAL_ENV를 읽지 않습니다. --active로 옵트인하거나 --no-active로 경고를 무시합니다.

빌드 격리(Build isolation)

기본적으로 uv는 PEP 517에 따라 선언된 빌드 의존성이 있는 격리된 가상환경에서 패키지를 빌드합니다.

일부 패키지(예: flash-attn, deepspeed)는 프로젝트에서 사용하는 것과 동일한 PyTorch 버전으로 빌드해야 합니다. 다른 패키지(예: cchardet)는 필요한 빌드 의존성을 실수로 누락합니다.

두 가지 접근 방식으로 이 문제를 해결합니다:

빌드 의존성 추가(Augmenting build dependencies)

extra-build-dependencies를 통해 추가 빌드 의존성을 추가합니다:

[tool.uv.extra-build-dependencies]
cchardet = ["cython"]

런타임 버전 일치를 위해 match-runtime = true를 사용합니다:

[tool.uv.extra-build-dependencies]
deepspeed = [{ requirement = "torch", match-runtime = true }]

이렇게 하면 deepspeed가 설치된 torch 버전으로 빌드됩니다.

flash-attn의 경우:

[project]
name = "project"
version = "0.1.0"
description = "..."
readme = "README.md"
requires-python = ">=3.12"
dependencies = ["flash-attn", "torch"]

[tool.uv.extra-build-dependencies]
flash-attn = [{ requirement = "torch", match-runtime = true }]

[tool.uv.extra-build-variables]
flash-attn = { FLASH_ATTENTION_SKIP_CUDA_BUILD = "TRUE" }

FLASH_ATTENTION_SKIP_CUDA_BUILD 변수는 소스 빌드 대신 사전 빌드된 wheel 해석을 활성화합니다.

동적 메타데이터(Dynamic metadata)

match-runtime = true는 정적 메타데이터를 필요로 합니다. 동적 메타데이터가 있는 패키지(예: axolotl)의 경우 정확한 버전을 지정합니다:

[project]
name = "project"
version = "0.1.0"
description = "..."
readme = "README.md"
requires-python = ">=3.12"
dependencies = ["axolotl[deepspeed, flash-attn]", "torch==2.6.0"]

[tool.uv.extra-build-dependencies]
axolotl = ["torch==2.6.0"]
deepspeed = ["torch==2.6.0"]
flash-attn = ["torch==2.6.0"]

또는 메타데이터를 미리 제공합니다:

[[tool.uv.dependency-metadata]]
name = "flash-attn"
version = "2.6.3"
requires-dist = ["torch", "einops"]

version 필드는 레지스트리 의존성에서는 선택적이지만, 직접 URL에서는 필수입니다.

빌드 격리 비활성화(Disabling build isolation)

빌드 격리를 비활성화해야 하는 패키지의 경우, 먼저 빌드 의존성을 설치한 후 격리 없이 패키지를 설치합니다.

cchardet 예시:

[project]
name = "project"
version = "0.1.0"
description = "..."
readme = "README.md"
requires-python = ">=3.12"
dependencies = ["cchardet", "cython", "setuptools"]

[tool.uv]
no-build-isolation-package = ["cchardet"]

uv sync를 실행하면 먼저 의존성을 설치한 후 격리 없이 cchardet를 설치합니다.

flash-attn의 경우:

[project]
name = "project"
version = "0.1.0"
description = "..."
readme = "README.md"
requires-python = ">=3.12"
dependencies = ["flash-attn", "torch"]

[tool.uv]
no-build-isolation-package = ["flash-attn"]

빌드 의존성을 선택적 그룹으로 격리하려면:

[project]
name = "project"
version = "0.1.0"
description = "..."
readme = "README.md"
requires-python = ">=3.12"
dependencies = ["cchardet"]

[project.optional-dependencies]
build = ["setuptools", "cython"]

[tool.uv]
no-build-isolation-package = ["cchardet"]

그런 다음 두 단계로 동기화합니다:

$ uv sync --extra build
 + cchardet==2.1.7
 + cython==3.1.3
 + setuptools==80.9.0
$ uv sync
 - cython==3.1.3
 - setuptools==80.9.0

해석 중 빌드 의존성이 필요한 패키지의 경우:

$ uv venv
$ uv pip install torch setuptools
$ uv sync

또는 해석 중 빌드 요구사항을 건너뛰기 위해 메타데이터를 미리 제공합니다:

[[tool.uv.dependency-metadata]]
name = "flash-attn"
version = "2.6.3"
requires-dist = ["torch", "einops"]

편집 가능 모드(Editable mode)

프로젝트는 기본적으로 편집 가능 모드로 설치되어 소스 변경 사항을 즉시 반영합니다. Docker와 같은 배포 시나리오에서는 uv sync 및 uv run에 --no-editable을 사용합니다.

충돌하는 의존성(Conflicting dependencies)

서로 다른 섹션의 의존성이 충돌하면 uv는 해석에 실패합니다. conflicts를 사용하여 명시적으로 비호환성을 선언합니다:

[tool.uv]
conflicts = [
    [
      { extra = "extra1" },
      { extra = "extra2" },
    ],
]

개발 그룹의 경우:

[tool.uv]
conflicts = [
    [
      { group = "group1" },
      { group = "group2" },
    ],
]

제한된 해석 환경(Limited resolution environments)

환경 마커를 통해 락파일 플랫폼을 제한합니다:

[tool.uv]
environments = [
    "sys_platform == 'darwin'",
    "sys_platform == 'linux'",
]

이렇게 하면 락파일에서 Windows가 제외됩니다.

필수 환경(Required environments)

특정 플랫폼을 필수로 지정합니다:

[tool.uv]
required-environments = [
    "sys_platform == 'darwin' and platform_machine == 'x86_64'",
]

이 요구사항은 주로 특정 환경을 위한 사전 빌드된 wheel만 배포하는 소스 배포가 없는 패키지(예: PyTorch)에 적용됩니다.

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

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