byteforce

CPN 한국어 자습서 · 외부 문서 한국어 미러

UV 문서 · Concepts

의존성 관리

Managing dependencies · 원문: docs.astral.sh/uv/concepts/projects/dependencies/

아래는 원문을 한국어로 옮긴 미러입니다. 코드·명령은 원문 그대로이며, 가장 최신 정보는 하단 원문 링크에서 확인하세요.

의존성 필드

의존성(dependency)은 여러 설정 필드에 걸쳐 구성됩니다:

의존성 추가

다음 명령어로 의존성을 추가합니다:

코드 · 명령
$ uv add httpx

이 명령어는 project.dependencies에 항목을 추가합니다:

코드 · 명령
[project]
name = "example"
version = "0.1.0"
dependencies = ["httpx>=0.27.2"]

대체 위치를 지정하려면 플래그를 사용합니다: - --dev: 개발 의존성 - --group: 특정 의존성 그룹 - --optional: 선택적 의존성

requirements 파일에서 의존성 가져오기

기존 requirements를 가져오려면 다음 명령어를 사용합니다:

코드 · 명령
uv add -r requirements.txt

의존성 제거

다음 명령어로 의존성을 제거합니다:

코드 · 명령
$ uv remove httpx

특정 테이블을 대상으로 하려면 --dev, --group, --optional 플래그를 사용합니다.

의존성 변경

버전 제약을 업데이트합니다:

코드 · 명령
$ uv add "httpx>0.1.0"

최신 호환 버전으로 강제 업데이트합니다:

코드 · 명령
$ uv add "httpx>0.1.0" --upgrade-package httpx

의존성 소스를 변경합니다:

코드 · 명령
$ uv add "httpx @ ../httpx"

플랫폼별 의존성

환경 마커(environment marker)를 사용하여 설치를 제한합니다:

코드 · 명령
$ uv add "jax; sys_platform == 'linux'"
$ uv add "numpy; python_version >= '3.11'"

결과 설정:

코드 · 명령
[project]
name = "project"
version = "0.1.0"
requires-python = ">=3.11"
dependencies = ["jax; sys_platform == 'linux'"]

프로젝트 의존성

project.dependencies 테이블은 PEP 621 표준을 따르며, 배포에 필요한 패키지를 지정합니다:

코드 · 명령
[project]
name = "albatross"
version = "0.1.0"
dependencies = [
  "tqdm >=4.66.2,<5",
  "torch ==2.2.2",
  "transformers[torch] >=4.39.3,<5",
  "importlib_metadata >=7.1.0,<8; python_version < '3.10'",
  "mollymawk ==0.1.0"
]

의존성 소스(Dependency sources)

tool.uv.sources 테이블은 패키지 레지스트리(registry) 외 대체 소스를 제공하며, 편집 가능(editable) 설치나 상대 경로 등의 패턴을 지원합니다:

코드 · 명령
[project]
name = "example"
version = "0.1.0"
dependencies = ["foo"]

[tool.uv.sources]
foo = { path = "./packages/foo" }

중요: 소스는 uv에서만 인식됩니다. 다른 도구를 사용하는 경우 해당 형식으로 재지정해야 합니다.

인덱스(Index)

특정 인덱스에 패키지를 고정합니다:

코드 · 명령
$ uv add torch --index pytorch=https://download.pytorch.org/whl/cpu

결과:

코드 · 명령
[project]
dependencies = ["torch"]

[tool.uv.sources]
torch = { index = "pytorch" }

[[tool.uv.index]]
name = "pytorch"
url = "https://download.pytorch.org/whl/cpu"

명시적으로 지정한 패키지로만 인덱스를 제한하려면 explicit = true를 추가합니다:

코드 · 명령
[[tool.uv.index]]
name = "pytorch"
url = "https://download.pytorch.org/whl/cpu"
explicit = true

Git

git+ 접두사를 사용하여 Git 의존성을 추가합니다:

코드 · 명령
$ uv add git+https://github.com/encode/httpx
$ uv add git+ssh://git@github.com/encode/httpx

결과 설정:

코드 · 명령
[project]
dependencies = ["httpx"]

[tool.uv.sources]
httpx = { git = "https://github.com/encode/httpx" }

Git 참조를 지정합니다:

코드 · 명령
$ uv add git+https://github.com/encode/httpx --tag 0.27.0
$ uv add git+https://github.com/encode/httpx --branch main
$ uv add git+https://github.com/encode/httpx --rev 326b9431c761e1ef1e00b9f760d1f654c8db48c6

해당 설정:

코드 · 명령
httpx = { git = "https://github.com/encode/httpx", tag = "0.27.0" }
httpx = { git = "https://github.com/encode/httpx", branch = "main" }
httpx = { git = "https://github.com/encode/httpx", rev = "326b9431c761e1ef1e00b9f760d1f654c8db48c6" }

서브디렉터리를 지정합니다:

코드 · 명령
$ uv add git+https://github.com/langchain-ai/langchain#subdirectory=libs/langchain
코드 · 명령
langchain = { git = "https://github.com/langchain-ai/langchain", subdirectory = "libs/langchain" }

Git LFS 지원은 소스별로 설정할 수 있습니다:

코드 · 명령
$ uv add --lfs git+https://github.com/astral-sh/lfs-cowsay
코드 · 명령
lfs-cowsay = { git = "https://github.com/astral-sh/lfs-cowsay", lfs = true }

중요: 이 기능을 사용하기 전에 Git LFS가 설치되어 있는지 확인하십시오.

URL

원격 wheel 또는 소스 배포를 추가합니다:

코드 · 명령
$ uv add "https://files.pythonhosted.org/packages/5c/2d/3da5bdf4408b8b2800061c339f240c1802f2e82d55e50bd39c5a881f47f0/httpx-0.27.0.tar.gz"

결과:

코드 · 명령
[project]
dependencies = ["httpx"]

[tool.uv.sources]
httpx = { url = "https://files.pythonhosted.org/packages/5c/2d/3da5bdf4408b8b2800061c339f240c1802f2e82d55e50bd39c5a881f47f0/httpx-0.27.0.tar.gz" }

소스 배포가 아카이브 루트에 없는 경우 선택적으로 subdirectory를 지정합니다.

경로(Path)

로컬 wheel, 소스 배포 또는 프로젝트 디렉터리를 추가합니다:

코드 · 명령
$ uv add /example/foo-0.1.0-py3-none-any.whl
$ uv add ./foo-0.1.0-py3-none-any.whl
$ uv add ~/projects/bar/

결과:

코드 · 명령
[project]
dependencies = ["foo"]

[tool.uv.sources]
foo = { path = "/example/foo-0.1.0-py3-none-any.whl" }

프로젝트 디렉터리에 편집 가능 설치를 추가합니다:

코드 · 명령
$ uv add --editable ../projects/bar/
코드 · 명령
[project]
dependencies = ["bar"]

[tool.uv.sources]
bar = { path = "../projects/bar", editable = true }

중요: 디렉터리 경로 의존성은 기본적으로 빌드를 시도합니다. 자세한 내용은 가상 의존성(virtual dependency)을 참조하십시오.

워크스페이스 멤버(Workspace member)

{ workspace = true }로 워크스페이스(workspace) 멤버 의존성을 선언합니다. 모든 워크스페이스 멤버는 명시적으로 지정해야 하며, 항상 편집 가능(editable) 상태입니다:

코드 · 명령
[project]
dependencies = ["foo==0.1.0"]

[tool.uv.sources]
foo = { workspace = true }

[tool.uv.workspace]
members = ["packages/foo"]

플랫폼별 소스

환경 마커를 사용하여 소스를 특정 플랫폼으로 제한합니다:

코드 · 명령
[project]
dependencies = ["httpx"]

[tool.uv.sources]
httpx = { git = "https://github.com/encode/httpx", tag = "0.27.2", marker = "sys_platform == 'darwin'" }

모든 플랫폼에 httpx를 설치하지만, macOS에서는 GitHub에서 다운로드하고 그 외 플랫폼에서는 PyPI로 폴백합니다.

다중 소스(Multiple sources)

PEP 508 환경 마커를 사용하여 하나의 의존성에 여러 소스를 지정합니다:

코드 · 명령
[project]
dependencies = ["httpx"]

[tool.uv.sources]
httpx = [
  { git = "https://github.com/encode/httpx", tag = "0.27.2", marker = "sys_platform == 'darwin'" },
  { git = "https://github.com/encode/httpx", tag = "0.24.1", marker = "sys_platform == 'linux'" },
]

인덱스에도 동일한 패턴을 적용합니다:

코드 · 명령
[project]
dependencies = ["torch"]

[tool.uv.sources]
torch = [
  { index = "torch-cpu", marker = "platform_system == 'Darwin'"},
  { index = "torch-gpu", marker = "platform_system == 'Linux'"},
]

[[tool.uv.index]]
name = "torch-cpu"
url = "https://download.pytorch.org/whl/cpu"
explicit = true

[[tool.uv.index]]
name = "torch-gpu"
url = "https://download.pytorch.org/whl/cu130"
explicit = true

소스 비활성화

tool.uv.sources 테이블을 무시하고 배포된 메타데이터로 의존성 해석을 시뮬레이션합니다:

코드 · 명령
$ uv lock --no-sources

이 명령어는 의존성을 충족시킬 수 있는 워크스페이스 멤버 검색도 방지합니다.

선택적 의존성(Optional dependencies)

선택적 의존성은 배포 라이브러리의 기본 의존성 트리를 줄입니다. [project.optional-dependencies]에 extra 이름과 의존성을 매핑하여 지정합니다:

코드 · 명령
[project]
name = "pandas"
version = "1.0.0"

[project.optional-dependencies]
plot = ["matplotlib>=3.6.3"]
excel = [
  "odfpy>=1.4.1",
  "openpyxl>=3.1.0",
  "python-calamine>=0.1.7",
  "pyxlsb>=1.0.10",
  "xlrd>=2.0.1",
  "xlsxwriter>=3.0.5"
]

선택적 의존성을 추가합니다:

코드 · 명령
$ uv add httpx --optional network

선택적 의존성은 tool.uv.sources의 소스를 지원하며 extras를 사용할 수 있습니다:

코드 · 명령
[project]
dependencies = []

[project.optional-dependencies]
cpu = ["torch"]
gpu = ["torch"]

[tool.uv.sources]
torch = [
  { index = "torch-cpu", extra = "cpu" },
  { index = "torch-gpu", extra = "gpu" },
]

[[tool.uv.index]]
name = "torch-cpu"
url = "https://download.pytorch.org/whl/cpu"

[[tool.uv.index]]
name = "torch-gpu"
url = "https://download.pytorch.org/whl/cu130"

참고: 충돌하는 선택적 의존성은 명시적인 충돌 선언이 필요합니다.

개발 의존성(Development dependencies)

개발 의존성은 로컬 전용이며 PyPI 배포에서 제외됩니다. [dependency-groups](PEP 735)에 선언합니다:

코드 · 명령
$ uv add --dev pytest

결과:

코드 · 명령
[dependency-groups]
dev = ["pytest >=8.1.1,<9"]

dev 그룹은 --dev, --only-dev, --no-dev 플래그로 특별히 처리되며, 기본적으로 동기화됩니다.

의존성 그룹(Dependency groups)

개발 의존성을 여러 그룹으로 나눕니다:

코드 · 명령
$ uv add --group lint ruff

결과:

코드 · 명령
[dependency-groups]
dev = ["pytest"]
lint = ["ruff"]

그룹을 포함하거나 제외하려면 다음 플래그를 사용합니다: - --all-groups: 모든 그룹 포함 - --no-default-groups: 기본 그룹 제외 - --group <name>: 특정 그룹 포함 - --only-group <name>: 특정 그룹만 포함 - --no-group <name>: 특정 그룹 제외

참고: --dev, --only-dev, --no-dev는 각각 --group dev, --only-group dev, --no-group dev와 동일합니다.

모든 의존성 그룹은 호환 가능해야 합니다. uv는 모든 그룹을 함께 해석합니다. 충돌하는 그룹은 명시적으로 충돌로 선언하지 않으면 의존성 해석에 실패합니다.

그룹 중첩(Nesting groups)

의존성 그룹은 다른 그룹을 포함할 수 있습니다:

코드 · 명령
[dependency-groups]
dev = [
  {include-group = "lint"},
  {include-group = "test"}
]
lint = ["ruff"]
test = ["pytest"]

포함된 그룹의 의존성은 상위 그룹의 다른 의존성과 충돌해서는 안 됩니다.

기본 그룹(Default groups)

기본적으로 uv는 dev 그룹을 포함합니다. 기본값을 변경하려면:

코드 · 명령
[tool.uv]
default-groups = ["dev", "foo"]

모든 그룹을 기본으로 활성화하려면:

코드 · 명령
[tool.uv]
default-groups = "all"

팁: uv run 또는 uv sync 실행 시 --no-default-groups를 사용하면 이 동작을 비활성화하거나, --no-group <name>으로 특정 그룹을 제외할 수 있습니다.

그룹 requires-python

의존성 그룹은 기본적으로 requires-python과 호환 가능해야 합니다. 다른 범위를 지정하려면:

코드 · 명령
[project]
name = "example"
version = "0.0.0"
requires-python = ">=3.10"

[dependency-groups]
dev = ["pytest"]

[tool.uv.dependency-groups]
dev = {requires-python = ">=3.12"}

레거시 dev-dependencies

[dependency-groups] 표준화 이전에 uv는 tool.uv.dev-dependencies를 사용했습니다:

코드 · 명령
[tool.uv]
dev-dependencies = ["pytest"]

이는 dependency-groups.dev와 결합됩니다. 이 필드는 향후 더 이상 사용되지 않을 예정입니다.

참고: tool.uv.dev-dependencies가 존재하면, uv add --dev는 dependency-groups.dev를 생성하는 대신 이 필드를 사용합니다.

빌드 의존성(Build dependencies)

Python 패키지는 [build-system]의 build-system.requires(PEP 518)에 빌드 시간 의존성을 선언합니다:

코드 · 명령
[project]
name = "pandas"
version = "0.1.0"

[build-system]
requires = ["setuptools>=42"]
build-backend = "setuptools.build_meta"

uv는 빌드 의존성을 해석할 때 tool.uv.sources를 따릅니다:

코드 · 명령
[project]
name = "pandas"
version = "0.1.0"

[build-system]
requires = ["setuptools>=42"]
build-backend = "setuptools.build_meta"

[tool.uv.sources]
setuptools = { path = "./packages/setuptools" }

배포 시에는 uv build --no-sources를 실행하여 pypa/build 같은 다른 도구와 올바르게 빌드되는지 확인하십시오.

편집 가능 의존성(Editable dependencies)

일반 Python 패키지 설치는 wheel을 빌드하고 파일을 복사합니다. 편집 가능 설치는 .pth 파일을 사용하여 소스와 직접 연결하므로, 재설치 없이 변경 사항을 반영합니다.

uv는 기본적으로 워크스페이스 패키지에 편집 가능 설치를 사용합니다.

편집 가능 의존성을 추가합니다:

코드 · 명령
$ uv add --editable ./path/foo

편집 가능 설치를 비활성화합니다:

코드 · 명령
$ uv add --no-editable ./path/foo

가상 의존성(Virtual dependencies)

가상 의존성(virtual dependency)은 패키지로 설치되지 않지만, 해당 의존성은 설치됩니다.

기본적으로 의존성은 가상이 아닙니다. tool.uv.package = false인 경로 의존성은 가상이 됩니다:

코드 · 명령
[project]
dependencies = ["bar"]

[tool.uv.sources]
bar = { path = "../projects/bar", package = false }

프로젝트 수준의 package = false를 재정의합니다:

코드 · 명령
[project]
dependencies = ["bar"]

[tool.uv.sources]
bar = { path = "../projects/bar", package = true }

워크스페이스 멤버도 마찬가지로 가상으로 만들 수 있습니다:

코드 · 명령
[project]
name = "parent"
version = "1.0.0"
dependencies = []

[tool.uv.workspace]
members = ["child"]

자식 패키지에 빌드 시스템이 없는 경우:

코드 · 명령
[project]
name = "child"
version = "1.0.0"
dependencies = ["anyio"]

이 경우 child는 가상이지만 anyio는 설치됩니다. 상위 패키지가 child에 의존성을 선언하면:

코드 · 명령
[project]
name = "parent"
version = "1.0.0"
dependencies = ["child"]

[tool.uv.sources]
child = { workspace = true }

[tool.uv.workspace]
members = ["child"]

child는 빌드되고 설치됩니다.

의존성 지정자(Dependency specifiers)

uv는 다음 요소로 구성된 표준 PEP 508 의존성 지정자를 사용합니다:

  1. 의존성 이름
  2. Extras (선택)
  3. 버전 지정자
  4. 환경 마커 (선택)

버전 지정자는 쉼표로 구분됩니다. foo >=1.2.3,<2,!=1.4.0은 1.2.3 이상, 2 미만, 1.4.0 제외를 의미합니다.

지정자는 뒤에 0을 채우므로, foo ==2는 2.0.0과 일치합니다.

별표 표기법을 사용합니다: foo ==2.1.*은 모든 2.1 릴리스를 허용합니다. ~=는 마지막 자리가 같거나 높은 버전과 일치합니다. foo ~=1.2는 foo >=1.2,<2와 같고, foo ~=1.2.3은 foo >=1.2.3,<1.3과 같습니다.

Extras는 대괄호 안에 쉼표로 구분합니다: pandas[excel,plot] ==2.2.

플랫폼별 의존성은 환경 마커를 사용합니다: importlib-metadata >=7.1.0,<8; python_version < '3.10' 또는 colorama >=0.4.6,<5; platform_system == "Windows".

마커는 and, or, 괄호로 조합합니다: aiohttp >=3.7.4,<4; (sys_platform != 'win32' or implementation_name != 'pypy') and python_version >= '3.10'. 마커 내의 버전은 따옴표로 묶어야 하며, 마커 외부의 버전은 따옴표를 사용하지 않습니다.

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

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