跳转至

PyTorch 安装#

概述#

本指南介绍如何将 PyTorch 与 pixi 集成，支持多种安装 PyTorch 的方式。

  • 使用 conda-forge Conda channel 安装 PyTorch（推荐）
  • 使用 pypi，通过我们的 uv 集成安装 PyTorch。（大多数版本可用）
  • 使用 pytorch Conda channel 安装（传统方式）

通过这些选项，你可以根据需求选择最佳的 PyTorch 安装方式。

系统要求#

在 PyTorch 上下文中，系统要求 帮助 Pixi 了解是否可以安装和使用 CUDA 相关的包。 这些要求确保依赖解析期间的兼容性。

这里的关键机制是使用 __cuda 等虚拟包。 虚拟包表示可用的系统能力（例如 CUDA 版本）。 通过指定 system-requirements.cuda = "12"，你告诉 Pixi CUDA 版本 12 可用，并且在解析期间可以使用。

例如：

  • 如果一个包依赖 __cuda >= 12，Pixi 将解析正确的版本。
  • 如果一个包依赖 __cuda 没有版本约束，则可以使用任何可用的 CUDA 版本。

如果不设置适当的 system-requirements.cuda，Pixi 将默认安装 PyTorch 及其依赖的 仅 CPU 版本。

可以在这里找到更深入的系统要求解释。

从 Conda-forge 安装#

你可以使用 conda-forge channel 安装 PyTorch。 这些是 conda-forge 社区维护的 PyTorch 构建。 你可以直接使用 Nvidia 提供的包，以确保这些包可以协同工作。

Bare minimum conda-forge pytorch with cuda installation
[workspace]
channels = ["https://prefix.dev/conda-forge"]
name = "pytorch-conda-forge"
platforms = ["linux-64", "win-64"]

[system-requirements]
cuda = "12.0"

[dependencies]
pytorch-gpu = "*"
Bare minimum conda-forge pytorch with cuda installation
[project]
name = "pytorch-conda-forge"

[tool.pixi.workspace]
channels = ["https://prefix.dev/conda-forge"]
platforms = ["linux-64"]

[tool.pixi.system-requirements]
cuda = "12.0"

[tool.pixi.dependencies]
pytorch-gpu = "*"

要故意安装特定版本的 cuda 包，你可以依赖 cuda-version 包，其他包将在解析时解释它。 cuda-version 包约束 __cuda 虚拟包和 cudatoolkit 包的版本。 这确保了正确版本的 cudatoolkit 包被安装，并且依赖树被正确解析。

Add cuda version to the conda-forge pytorch installation
[dependencies]
pytorch-gpu = "*"
cuda-version = "12.6.*"
Add cuda version to the conda-forge pytorch installation
[tool.pixi.dependencies]
pytorch-gpu = "*"
cuda-version = "12.6.*"

使用 conda-forge，你也可以安装 PyTorch 的 cpu 版本。 一个常见的用例是拥有两个环境，一个用于 CUDA 机器，一个用于非 CUDA 机器。

Adding a cpu environment
[workspace]
channels = ["https://prefix.dev/conda-forge"]
name = "pytorch-conda-forge"
platforms = ["linux-64"]

[feature.gpu.system-requirements]
cuda = "12.0"

[feature.gpu.dependencies]
cuda-version = "12.6.*"
pytorch-gpu = "*"

[feature.cpu.dependencies]
pytorch-cpu = "*"

[environments]
cpu = ["cpu"]
default = ["gpu"]
Split into environments and add a CPU environment
[project]
name = "pytorch-conda-forge"

[tool.pixi.workspace]
channels = ["https://prefix.dev/conda-forge"]
platforms = ["linux-64"]

[tool.pixi.feature.gpu.system-requirements]
cuda = "12.0"

[tool.pixi.feature.gpu.dependencies]
cuda-version = "12.6.*"
pytorch-gpu = "*"

[tool.pixi.feature.cpu.dependencies]
pytorch-cpu = "*"

[tool.pixi.environments]
cpu = ["cpu"]
default = ["gpu"]

然后可以使用 pixi run 命令运行这些环境。 

pixi run --environment cpu python -c "import torch; print(torch.cuda.is_available())"
pixi run -e gpu python -c "import torch; print(torch.cuda.is_available())"

现在你应该可以用你的依赖和任务来扩展它了。

以下是一些值得注意的包的链接：

从 PyPI 安装#

由于与 uv 的集成，我们也可以从 pypi 安装 PyTorch。

混合 [dependencies] 和 [pypi-dependencies]

当使用这种方式安装 torch 包时，你也应该从 pypi 安装依赖于 torch 的包。 因此，如果 PyPI 包有来自 Conda 包的依赖，就不要将 PyPI 包与 Conda 包混合使用。

原因是我们的解析是两步过程，首先解析 Conda 包，然后解析 PyPI 包。 因此，如果我们需要 Conda 包依赖 PyPI 包，这就无法成功。

Pytorch 索引#

PyTorch 包通过自定义索引提供，类似于 Conda channel，由 PyTorch 团队维护。 要从 PyTorch 索引安装 PyTorch，你需要将索引添加到 manifest。 最好按依赖项强制使用索引。

Install PyTorch from pypi
[workspace]
channels = ["https://prefix.dev/conda-forge"]
name = "pytorch-pypi"
platforms = ["osx-arm64", "linux-64", "win-64"]

[dependencies]
# We need a python version that is compatible with pytorch
python = ">=3.11,<3.13"

[pypi-dependencies]
torch = { version = ">=2.5.1", index = "https://download.pytorch.org/whl/cu124" }
torchvision = { version = ">=0.20.1", index = "https://download.pytorch.org/whl/cu124" }

[target.osx.pypi-dependencies]
# OSX has no CUDA support so use the CPU here
torch = { version = ">=2.5.1", index = "https://download.pytorch.org/whl/cpu" }
torchvision = { version = ">=0.20.1", index = "https://download.pytorch.org/whl/cpu" }
Install PyTorch from pypi
[project]
name = "pytorch-pypi"
# We need a python version that is compatible with pytorch
requires-python = ">= 3.11,<3.13"

[tool.pixi.workspace]
channels = ["https://prefix.dev/conda-forge"]
platforms = ["osx-arm64", "linux-64", "win-64"]

[tool.pixi.pypi-dependencies]
torch = { version = ">=2.5.1", index = "https://download.pytorch.org/whl/cu124" }
torchvision = { version = ">=0.20.1", index = "https://download.pytorch.org/whl/cu124" }

[tool.pixi.target.osx.pypi-dependencies]
# OSX has no CUDA support so use the CPU here
torch = { version = ">=2.5.1", index = "https://download.pytorch.org/whl/cpu" }
torchvision = { version = ">=0.20.1", index = "https://download.pytorch.org/whl/cpu" }

你可以告诉 Pixi 使用多个环境来安装多个版本的 PyTorch，无论是 cpu 还是 gpu。

Use multiple environments for the pypi pytorch installation
[workspace]
channels = ["https://prefix.dev/conda-forge"]
name = "pytorch-pypi-envs"
platforms = ["linux-64", "win-64"]

[dependencies]
# We need a python version that is compatible with pytorch
python = ">=3.11,<3.13"

[feature.gpu]
system-requirements = { cuda = "12.0" }
[feature.gpu.pypi-dependencies]
torch = { version = ">=2.5.1", index = "https://download.pytorch.org/whl/cu124" }
torchvision = { version = ">=0.20.1", index = "https://download.pytorch.org/whl/cu124" }

[feature.cpu.pypi-dependencies]
torch = { version = ">=2.5.1", index = "https://download.pytorch.org/whl/cpu" }
torchvision = { version = ">=0.20.1", index = "https://download.pytorch.org/whl/cpu" }

[environments]
gpu = { features = ["gpu"] }
# Make CPU the default environment
default = { features = ["cpu"] }
Use multiple environments for the pypi pytorch installation
[project]
name = "pytorch-pypi-envs"
# We need a python version that is compatible with pytorch
requires-python = ">= 3.11,<3.13"

[tool.pixi.workspace]
channels = ["https://prefix.dev/conda-forge"]
platforms = ["linux-64", "win-64"]

[tool.pixi.feature.gpu]
system-requirements = { cuda = "12.0" }

[tool.pixi.feature.gpu.pypi-dependencies]
torch = { version = ">=2.5.1", index = "https://download.pytorch.org/whl/cu124" }
torchvision = { version = ">=0.20.1", index = "https://download.pytorch.org/whl/cu124" }

[tool.pixi.feature.cpu.pypi-dependencies]
torch = { version = ">=2.5.1", index = "https://download.pytorch.org/whl/cpu" }
torchvision = { version = ">=0.20.1", index = "https://download.pytorch.org/whl/cpu" }

[tool.pixi.environments]
gpu = { features = ["gpu"] }
# Make CPU the default environment
default = { features = ["cpu"] }

然后可以使用 pixi run 命令运行这些环境。 

pixi run --environment cpu python -c "import torch; print(torch.__version__); print(torch.cuda.is_available())"
pixi run -e gpu python -c "import torch; print(torch.__version__); print(torch.cuda.is_available())"

混合 macOS 和 CUDA 与 pypi-dependencies#

使用 pypi-dependencies 时，Pixi 创建一个 "solve" 环境来解析 PyPI 依赖。 这个过程涉及首先安装 Conda 依赖，然后在该环境中解析 PyPI 包。

如果你在 macOS 机器上并尝试解析 Linux 或 Windows 的 CUDA 版本 PyTorch，这可能会出现问题。 由于 macOS 不支持 CUDA 的 Conda 依赖，它无法安装 solve 环境，从而无法正确解析。

当前状态： Pixi 维护者知道这个限制，并正在积极努力实现此类情况的跨平台依赖解析。

同时，你可能需要在支持 CUDA 的机器上运行解析过程，例如 Linux 或 Windows 主机。

从 PyTorch channel 安装#

Warning

这依赖于 Anaconda 的非免费 main channel，将其与 conda-forge 混合会导致冲突。

Note

这是安装 pytorch 的传统方式，由于 PyTorch 已停止更新 their channel，这将不会更新到后续版本。

Install PyTorch from the PyTorch channel
[workspace]
name = "pytorch-from-pytorch-channel"
# `main` is not free! It's a paid channel for organizations over 200 people.
channels = ["main", "nvidia", "pytorch"]
platforms = ["osx-arm64", "linux-64", "win-64"]

[feature.gpu.system-requirements]
cuda = "12.0"

[dependencies]
pytorch = "*"

[environments]
gpu = ["gpu"]
Install PyTorch from the PyTorch channel
[project]
name = "pytorch-from-pytorch-channel"
requires-python = ">= 3.11, < 3.13"
version = "0.1.0"

[tool.pixi.workspace]
# `main` is not free! It's a paid channel for organizations over 200 people.
channels = ["main", "nvidia", "pytorch"]
platforms = ["osx-arm64", "linux-64", "win-64"]

[tool.pixi.feature.gpu.system-requirements]
cuda = "12.0"

[tool.pixi.dependencies]
pytorch = "*"

[tool.pixi.environments]
gpu = ["gpu"]

故障排除#

如果你在弄清楚为什么 PyTorch 安装不工作时遇到困难，请通过创建 PR 到本文档来与社区分享你的解决方案或提示。

测试 PyTorch 安装#

你可以用这个命令验证你的 PyTorch 安装：

pixi run python -c "import torch; print(torch.__version__); print(torch.cuda.is_available())"

检查你机器的 CUDA 版本#

要检查 Pixi 在你的机器上检测到的 CUDA 版本，运行：

pixi info

示例输出： 

...
Virtual packages: __unix=0=0
                : __linux=6.5.9=0
                : __cuda=12.5=0
...

如果缺少 __cuda，你可以使用 NVIDIA 工具验证系统的 CUDA 版本： 

nvidia-smi

要检查环境中安装的 CUDA 工具包版本：

pixi run nvcc --version

安装损坏的原因#

安装损坏通常是由于混合不兼容的 channel 或包来源造成的：

  1. 混合 Conda Channel

    同时使用 conda-forge 和传统的 pytorch channel 会导致冲突。 选择一个 channel 并坚持使用它，以避免环境中的问题。

  2. 混合 Conda 和 PyPI 包

    如果你从 pypi 安装 PyTorch，所有依赖于 torch 的包也必须来自 PyPI。 在同一依赖链中混合 Conda 和 PyPI 包会导致冲突。

总结：

  • 选择一个 Conda channel（conda-forge 或 pytorch）来获取 pytorch，并避免混合。
  • 对于 PyPI 安装，确保所有相关包都来自 PyPI。

GPU 版本的 pytorch 没有安装：#

  1. 使用 conda-Forge
    • 确保设置了 system-requirements.cuda 以通知 Pixi 安装支持 CUDA 的包。
    • 使用 cuda-version 包来固定所需的 CUDA 版本。
  2. 使用 PyPI
    • 使用适当的 PyPI 索引来获取支持 CUDA 的正确轮子。

解析失败#

如果你看到这样的错误：

ABI 标签不匹配 

├─▶ failed to resolve pypi dependencies
╰─▶ Because only the following versions of torch are available:
      torch<=2.5.1
      torch==2.5.1+cpu
  and torch==2.5.1 has no wheels with a matching Python ABI tag, we can conclude that torch>=2.5.1,<2.5.1+cpu cannot be used.
  And because torch==2.5.1+cpu has no wheels with a matching platform tag and you require torch>=2.5.1, we can conclude that your requirements are
  unsatisfiable.
这是因为 Python ABI 标签（应用程序二进制接口）与可用的 PyPI 轮子不匹配。

解决方案：

  • 检查你的 Python 版本，确保它与 torch 的 PyPI 轮子兼容。 ABI 标签基于 Python 版本，嵌入在轮子文件名中，例如 Python 3.12 的 cp312。
  • 如有需要，降低配置中的 requires-python 或 python 版本。
  • 例如，截至目前，PyTorch 不完全支持 Python 3.13；使用 Python 3.12 或更早版本。

平台标签不匹配 

├─▶ failed to resolve pypi dependencies
╰─▶ Because only the following versions of torch are available:
    torch<=2.5.1
    torch==2.5.1+cu124
and torch>=2.5.1 has no wheels with a matching platform tag, we can conclude that torch>=2.5.1,<2.5.1+cu124 cannot be used.
And because you require torch>=2.5.1, we can conclude that your requirements are unsatisfiable.
这是因为平台标签与可安装的 PyPI 轮子不匹配。

示例问题： torch==2.5.1+cu124（CUDA 12.4）尝试在 osx 机器上运行，但此版本仅适用于 linux-64 和 win-64。

解决方案： - 使用适合你平台的正确 PyPI 索引： - 仅 CPU：为所有平台使用 cpu 索引。 - CUDA 版本：为 linux-64 和 win-64 使用 cu124。

正确的索引： - CPU：https://download.pytorch.org/whl/cpu - CUDA 12.4：https://download.pytorch.org/whl/cu124

这确保 PyTorch 安装与你的系统平台和 Python 版本兼容。