PyTorch와 함께 uv 사용하기¶
PyTorch는 딥러닝 연구와 개발에 널리 사용되는 인기 있는 프레임워크이다. uv를 사용하면 다양한 Python 버전과 환경에서 PyTorch 프로젝트와 PyTorch 의존성을 관리할 수 있다. 또한 가속기 선택(예: CPU 전용 vs. CUDA)도 제어할 수 있다.
Note
이 가이드에 설명된 일부 기능은 uv 버전 0.5.3 이상이 필요하다. 이전 버전의 uv를 사용 중이라면 PyTorch를 설정하기 전에 업그레이드하는 것을 권장한다.
PyTorch 설치하기¶
패키징 관점에서 PyTorch는 몇 가지 독특한 특징을 가지고 있다:
- 많은 PyTorch 휠(wheel) 파일이 Python Package Index(PyPI)가 아닌 전용 인덱스에 호스팅된다. 따라서 PyTorch를 설치하려면 프로젝트가 PyTorch 인덱스를 사용하도록 설정해야 한다.
- PyTorch는 각 가속기(예: CPU 전용, CUDA)에 대해 별도의 빌드를 생성한다. 이러한 가속기를 지정하기 위한 표준화된 메커니즘이 없기 때문에, PyTorch는 이를 로컬 버전 지정자에 인코딩한다. 따라서 PyTorch 버전은 종종
2.5.1+cpu,2.5.1+cu121등으로 표시된다. - 서로 다른 가속기를 위한 빌드는 각기 다른 인덱스에 게시된다. 예를 들어,
+cpu빌드는 https://download.pytorch.org/whl/cpu에 게시되고,+cu121빌드는 https://download.pytorch.org/whl/cu121에 게시된다.
따라서 필요한 패키징 설정은 지원하려는 플랫폼과 활성화하려는 가속기에 따라 달라진다.
시작하기 위해, uv init --python 3.12를 실행한 후 uv add torch torchvision을 실행하면 생성되는 다음 (기본) 설정을 고려해 보자.
이 경우 PyTorch는 PyPI에서 설치된다. PyPI는 Windows와 macOS용 CPU 전용 휠과 Linux용 GPU 가속 휠(CUDA 12.4 대상)을 호스팅한다:
[project]
name = "project"
version = "0.1.0"
requires-python = ">=3.12"
dependencies = [
"torch>=2.6.0",
"torchvision>=0.21.0",
]
지원되는 Python 버전
작성 시점에서 PyTorch는 아직 Python 3.13용 휠을 게시하지 않았다. 따라서 requires-python = ">=3.13"인 프로젝트는 해결에 실패할 수 있다. 호환성 매트릭스를 참고하자.
이 설정은 Windows와 macOS에서 CPU 빌드를 사용하고 Linux에서 CUDA 지원 빌드를 사용하려는 프로젝트에 유효하다. 그러나 다른 플랫폼이나 가속기를 지원해야 한다면, 프로젝트를 그에 맞게 설정해야 한다.
PyTorch 인덱스 사용하기¶
특정 플랫폼에서만 PyTorch의 특정 버전을 사용하고 싶을 때가 있다. 예를 들어, Linux에서도 CPU 전용 빌드를 사용하고 싶을 수 있다.
이런 경우, 먼저 pyproject.toml에 해당 PyTorch 인덱스를 추가한다:
=== "CPU 전용"
```toml
[[tool.uv.index]]
name = "pytorch-cpu"
url = "https://download.pytorch.org/whl/cpu"
explicit = true
```
=== "CUDA 11.8"
```toml
[[tool.uv.index]]
name = "pytorch-cu118"
url = "https://download.pytorch.org/whl/cu118"
explicit = true
```
=== "CUDA 12.1"
```toml
[[tool.uv.index]]
name = "pytorch-cu121"
url = "https://download.pytorch.org/whl/cu121"
explicit = true
```
=== "CUDA 12.4"
```toml
[[tool.uv.index]]
name = "pytorch-cu124"
url = "https://download.pytorch.org/whl/cu124"
explicit = true
```
=== "ROCm6"
```toml
[[tool.uv.index]]
name = "pytorch-rocm"
url = "https://download.pytorch.org/whl/rocm6.2"
explicit = true
```
=== "Intel GPU"
```toml
[[tool.uv.index]]
name = "pytorch-xpu"
url = "https://download.pytorch.org/whl/xpu"
explicit = true
```
explicit = true를 사용하면 이 인덱스가 torch, torchvision 및 기타 PyTorch 관련 패키지에만 적용된다. jinja2와 같은 일반 의존성은 기본 인덱스(PyPI)에서 계속 가져오게 된다.
다음으로, pyproject.toml을 업데이트해 torch와 torchvision이 원하는 인덱스를 가리키도록 설정한다:
=== "CPU 전용"
```toml
[tool.uv.sources]
torch = [
{ index = "pytorch-cpu" },
]
torchvision = [
{ index = "pytorch-cpu" },
]
```
=== "CUDA 11.8"
PyTorch는 macOS용 CUDA 빌드를 제공하지 않는다. 따라서 `sys_platform`을 사용해 Linux와 Windows에서는 PyTorch 인덱스를 사용하고, macOS에서는 PyPI로 대체하도록 설정한다:
```toml
[tool.uv.sources]
torch = [
{ index = "pytorch-cu118", marker = "sys_platform == 'linux' or sys_platform == 'win32'" },
]
torchvision = [
{ index = "pytorch-cu118", marker = "sys_platform == 'linux' or sys_platform == 'win32'" },
]
```
=== "CUDA 12.1"
PyTorch는 macOS용 CUDA 빌드를 제공하지 않는다. 따라서 `sys_platform`을 사용해 Linux와 Windows에서는 PyTorch 인덱스를 사용하고, macOS에서는 PyPI로 대체하도록 설정한다:
```toml
[tool.uv.sources]
torch = [
{ index = "pytorch-cu121", marker = "sys_platform == 'linux' or sys_platform == 'win32'" },
]
torchvision = [
{ index = "pytorch-cu121", marker = "sys_platform == 'linux' or sys_platform == 'win32'" },
]
```
=== "CUDA 12.4"
PyTorch는 macOS용 CUDA 빌드를 제공하지 않는다. 따라서 `sys_platform`을 사용해 Linux와 Windows에서는 PyTorch 인덱스를 사용하고, macOS에서는 PyPI로 대체하도록 설정한다:
```toml
[tool.uv.sources]
torch = [
{ index = "pytorch-cu124", marker = "sys_platform == 'linux' or sys_platform == 'win32'" },
]
torchvision = [
{ index = "pytorch-cu124", marker = "sys_platform == 'linux' or sys_platform == 'win32'" },
]
```
=== "ROCm6"
PyTorch는 macOS와 Windows용 ROCm6 빌드를 제공하지 않는다. 따라서 `sys_platform`을 사용해 Linux에서는 PyTorch 인덱스를 사용하고, macOS와 Windows에서는 PyPI로 대체하도록 설정한다:
```toml
[tool.uv.sources]
torch = [
{ index = "pytorch-rocm", marker = "sys_platform == 'linux'" },
]
torchvision = [
{ index = "pytorch-rocm", marker = "sys_platform == 'linux'" },
]
```
=== "Intel GPU"
PyTorch는 macOS용 Intel GPU 빌드를 제공하지 않는다. 따라서 `sys_platform`을 사용해 Linux와 Windows에서는 PyTorch 인덱스를 사용하고, macOS에서는 PyPI로 대체하도록 설정한다:
```toml
[tool.uv.sources]
torch = [
{ index = "pytorch-xpu", marker = "sys_platform == 'linux' or sys_platform == 'win32'" },
]
torchvision = [
{ index = "pytorch-xpu", marker = "sys_platform == 'linux' or sys_platform == 'win32'" },
]
# Intel GPU 지원은 Linux에서 `pytorch-triton-xpu`가 필요하며, 이 역시 PyTorch 인덱스에서 설치해야 한다.
pytorch-triton-xpu = [
{ index = "pytorch-xpu", marker = "sys_platform == 'linux'" },
]
```
다음은 모든 플랫폼에서 PyTorch의 CPU 전용 빌드를 사용하는 완전한 예제이다:
[project]
name = "project"
version = "0.1.0"
requires-python = ">=3.12.0"
dependencies = [
"torch>=2.6.0",
"torchvision>=0.21.0",
]
[tool.uv.sources]
torch = [
{ index = "pytorch-cpu" },
]
torchvision = [
{ index = "pytorch-cpu" },
]
[[tool.uv.index]]
name = "pytorch-cpu"
url = "https://download.pytorch.org/whl/cpu"
explicit = true
환경 마커를 사용해 가속기 설정하기¶
특정 환경에서는 CPU 전용 빌드를 사용하고, 다른 환경에서는 CUDA 지원 빌드를 사용해야 할 때가 있다. 예를 들어, macOS와 Windows에서는 CPU 전용 빌드를, Linux에서는 CUDA 지원 빌드를 사용할 수 있다.
tool.uv.sources를 사용하면 각 플랫폼에 적합한 인덱스를 환경 마커로 지정할 수 있다. 다음 설정은 Windows와 macOS에서는 PyTorch의 CPU 전용 빌드를 사용하고, Linux에서는 CUDA 지원 빌드를 사용한다.
[project]
name = "project"
version = "0.1.0"
requires-python = ">=3.12.0"
dependencies = [
"torch>=2.6.0",
"torchvision>=0.21.0",
]
[tool.uv.sources]
torch = [
{ index = "pytorch-cpu", marker = "sys_platform == 'win32'" },
{ index = "pytorch-cu124", marker = "sys_platform == 'linux'" },
]
torchvision = [
{ index = "pytorch-cpu", marker = "sys_platform == 'win32'" },
{ index = "pytorch-cu124", marker = "sys_platform == 'linux'" },
]
[[tool.uv.index]]
name = "pytorch-cpu"
url = "https://download.pytorch.org/whl/cpu"
explicit = true
[[tool.uv.index]]
name = "pytorch-cu124"
url = "https://download.pytorch.org/whl/cu124"
explicit = true
비슷한 방식으로, Windows와 Linux에서는 PyTorch의 Intel GPU 빌드를 사용하고, macOS에서는 CPU 전용 빌드를 사용할 수 있다.
[project]
name = "project"
version = "0.1.0"
requires-python = ">=3.12.0"
dependencies = [
"torch>=2.6.0",
"torchvision>=0.21.0",
"pytorch-triton-xpu>=3.2.0 ; sys_platform == 'linux'",
]
[tool.uv.sources]
torch = [
{ index = "pytorch-xpu", marker = "sys_platform == 'win32' or sys_platform == 'linux'" },
]
torchvision = [
{ index = "pytorch-xpu", marker = "sys_platform == 'win32' or sys_platform == 'linux'" },
]
pytorch-triton-xpu = [
{ index = "pytorch-xpu", marker = "sys_platform == 'linux'" },
]
[[tool.uv.index]]
name = "pytorch-xpu"
url = "https://download.pytorch.org/whl/xpu"
explicit = true
선택적 의존성으로 가속기 설정하기¶
특정 상황에서는 CPU 전용 빌드를 사용하고, 다른 경우에는 CUDA 지원 빌드를 사용해야 할 수 있다. 이때 사용자가 제공하는 extra를 통해 선택할 수 있다(예: uv sync --extra cpu vs. uv sync --extra cu124).
tool.uv.sources를 사용하면 각 활성화된 extra에 대해 원하는 인덱스를 지정할 수 있다. 예를 들어, 다음 설정은 uv sync --extra cpu에 대해 PyTorch의 CPU 전용 빌드를, uv sync --extra cu124에 대해 CUDA 지원 빌드를 사용한다.
[project]
name = "project"
version = "0.1.0"
requires-python = ">=3.12.0"
dependencies = []
[project.optional-dependencies]
cpu = [
"torch>=2.6.0",
"torchvision>=0.21.0",
]
cu124 = [
"torch>=2.6.0",
"torchvision>=0.21.0",
]
[tool.uv]
conflicts = [
[
{ extra = "cpu" },
{ extra = "cu124" },
],
]
[tool.uv.sources]
torch = [
{ index = "pytorch-cpu", extra = "cpu" },
{ index = "pytorch-cu124", extra = "cu124" },
]
torchvision = [
{ index = "pytorch-cpu", extra = "cpu" },
{ index = "pytorch-cu124", extra = "cu124" },
]
[[tool.uv.index]]
name = "pytorch-cpu"
url = "https://download.pytorch.org/whl/cpu"
explicit = true
[[tool.uv.index]]
name = "pytorch-cu124"
url = "https://download.pytorch.org/whl/cu124"
explicit = true
Note
macOS에서는 GPU 가속 빌드를 사용할 수 없으므로, cu124 extra가 활성화된 상태에서 위 설정은 macOS에서 설치에 실패한다.
uv pip 인터페이스¶
앞서 설명한 예제들은 주로 uv의 프로젝트 인터페이스(uv lock, uv sync, uv run 등)에 초점을 맞췄다. 하지만 PyTorch는 uv pip 인터페이스를 통해서도 설치할 수 있다.
PyTorch는 특정 환경 설정에 맞는 pip 커맨드를 결정하기 위해 전용 인터페이스를 제공한다. 예를 들어, Linux에서 CPU 전용의 안정적인 PyTorch 버전을 설치하려면 다음과 같이 실행한다:
$ pip3 install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cpu
uv를 사용해 동일한 작업을 수행하려면 pip3 대신 uv pip을 사용한다:
$ uv pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cpu