From aad6eb49014dc0b5c4ecc630fe1c53cd5e37b5ac Mon Sep 17 00:00:00 2001 From: Ruben Arts Date: Mon, 16 Dec 2024 14:39:12 +0100 Subject: [PATCH] docs: add pytorch integration guide. --- docs/features/pytorch.md | 140 ++++++++++++++++++ docs/reference/pixi_manifest.md | 1 + .../pixi_tomls/pytorch-conda-forge.toml | 31 ++++ .../pytorch-from-pytorch-channel.toml | 16 ++ .../source_files/pixi_tomls/pytorch-pypi.toml | 19 +++ .../pyproject_tomls/pytorch-conda-forge.toml | 33 +++++ .../pytorch-from-pytorch-channel.toml | 20 +++ .../pyproject_tomls/pytorch-pypi.toml | 19 +++ mkdocs.yml | 1 + tests/integration_rust/project_tests.rs | 15 ++ 10 files changed, 295 insertions(+) create mode 100644 docs/features/pytorch.md create mode 100644 docs/source_files/pixi_tomls/pytorch-conda-forge.toml create mode 100644 docs/source_files/pixi_tomls/pytorch-from-pytorch-channel.toml create mode 100644 docs/source_files/pixi_tomls/pytorch-pypi.toml create mode 100644 docs/source_files/pyproject_tomls/pytorch-conda-forge.toml create mode 100644 docs/source_files/pyproject_tomls/pytorch-from-pytorch-channel.toml create mode 100644 docs/source_files/pyproject_tomls/pytorch-pypi.toml diff --git a/docs/features/pytorch.md b/docs/features/pytorch.md new file mode 100644 index 000000000..443e6bafe --- /dev/null +++ b/docs/features/pytorch.md @@ -0,0 +1,140 @@ +# Pytorch Integration Guide + +## Overview +This guide explains how to integrate PyTorch with `pixi`, it supports multiple ways of installing PyTorch. + +- Install PyTorch using `conda-forge` Conda channel (Recommended) +- Install PyTorch using `pypi`, using our `uv`'s integration. (Most versions available) +- Install PyTorch using `pytorch` Conda channel (Legacy) + +With these options you can choose the best way to install PyTorch based on your requirements. + +## Installing from Conda-forge +You can install PyTorch using the `conda-forge` channel. +These are the community maintained builds of PyTorch. +You can make direct use of the Nvidia provided packages to make sure the packages can work together. + +!!! note + Currently not well-supported for Windows, but there is lots of work being done to get this working. + Follow the work on the [feedstock](https://github.com/conda-forge/pytorch-cpu-feedstock) +!!! note + Pixi uses the `system-requirements.cuda` to tell it can use the `cuda` packages. + Without it, pixi will install the `cpu` versions. + +=== "`pixi.toml`" + ```toml title="Bare minimum conda-forge pytorch with cuda installation" + --8<-- "docs/source_files/pixi_tomls/pytorch-conda-forge.toml:minimal" + ``` +=== "`pyproject.toml`" + ```toml title="Bare minimum conda-forge pytorch with cuda installation" + --8<-- "docs/source_files/pyproject_tomls/pytorch-conda-forge.toml:minimal" + ``` + +To deliberately install a specific version of the `cuda` packages you can depend on the `cuda-version` package which will then be interpreted by the other packages at resolve time. +Without specifying the `cuda-version` package, the latest version of cuda will be installed. +=== "`pixi.toml`" + ```toml title="Add cuda version to the conda-forge pytorch installation" + --8<-- "docs/source_files/pixi_tomls/pytorch-conda-forge.toml:cuda-version" + ``` +=== "`pyproject.toml`" + ```toml title="Add cuda version to the conda-forge pytorch installation" + --8<-- "docs/source_files/pyproject_tomls/pytorch-conda-forge.toml:cuda-version" + ``` + +With `conda-forge` you can also install the `cpu` version of PyTorch. +A common use-case is having two environments, one for CUDA machines and one for none-CUDA machines. + +=== "`pixi.toml`" + ```toml title="Adding a cpu environment" + --8<-- "docs/source_files/pixi_tomls/pytorch-conda-forge.toml:use-envs" + ``` +=== "`pyproject.toml`" + ```toml title="Split into environments and add a CPU environment" + --8<-- "docs/source_files/pyproject_tomls/pytorch-conda-forge.toml:use-envs" + ``` + +Now you should be able to extend that with your dependencies and tasks. + +Links to notable packages: + +- [pytorch](https://prefix.dev/channels/conda-forge/packages/pytorch) +- [pytorch-cpu](https://prefix.dev/channels/conda-forge/packages/pytorch-cpu) +- [pytorch-gpu](https://prefix.dev/channels/conda-forge/packages/pytorch-gpu) +- [torchvision](https://prefix.dev/channels/conda-forge/packages/torchvision) +- [torchaudio](https://prefix.dev/channels/conda-forge/packages/torchaudio) +- [cuda-version](https://prefix.dev/channels/conda-forge/packages/cuda-version) + +## Installing from PyPi +Thanks to the integration with `uv` we can also install PyTorch from `pypi`. + +### Pytorch index +PyTorch packages are provided through a custom index, which is maintained by the PyTorch team. +To install PyTorch from the PyTorch index, you need to add the indexes to manifest. +Best to do this per dependency to force the index to be used. + +- CPU only: [https://download.pytorch.org/whl/cpu](https://download.pytorch.org/whl/cpu) +- CUDA 11.8: [https://download.pytorch.org/whl/cu118](https://download.pytorch.org/whl/cu118) +- CUDA 12.1: [https://download.pytorch.org/whl/cu121](https://download.pytorch.org/whl/cu121) +- CUDA 12.4: [https://download.pytorch.org/whl/cu124](https://download.pytorch.org/whl/cu124) +- ROCm6: [https://download.pytorch.org/whl/rocm6.2](https://download.pytorch.org/whl/rocm6.2) + +=== "`pixi.toml`" + ```toml title="Install PyTorch from pypi" + --8<-- "docs/source_files/pixi_tomls/pytorch-pypi.toml:minimal" + ``` +=== "`pyproject.toml`" + ```toml title="Install PyTorch from pypi" + --8<-- "docs/source_files/pyproject_tomls/pytorch-pypi.toml:minimal" + ``` + +## Installing from PyTorch channel +!!! warning + This depends on the [non-free](https://www.anaconda.com/blog/is-conda-free) `main` channel from Anaconda and mixing it with `conda-forge` can lead to conflicts. + +!!! note + This is the [legacy](https://dev-discuss.pytorch.org/t/pytorch-deprecation-of-conda-nightly-builds/2590) way of installing pytorch, this will not be updated to later versions as pytorch has discontinued their channel. + +=== "`pixi.toml`" + ```toml title="Install PyTorch from the PyTorch channel" + --8<-- "docs/source_files/pixi_tomls/pytorch-from-pytorch-channel.toml:minimal" + ``` +=== "`pyproject.toml`" + ```toml title="Install PyTorch from the PyTorch channel" + --8<-- "docs/source_files/pyproject_tomls/pytorch-from-pytorch-channel.toml:minimal" + ``` + +## Troubleshooting + +- You can test the installation with the following command: +```shell +pixi run python -c "import torch; print(torch.__version__); print(torch.cuda.is_available())" +``` +- You can ask pixi which version of CUDA it finds on your computer with `pixi info`. +``` +> pixi info +... +Virtual packages: __unix=0=0 + : __linux=6.5.9=0 + : __cuda=12.5=0 +... +``` +- Installing `torch` from PyPI and other packages from Conda channels doesn't work. + - The lowest level package in the dependency tree that uses a PyPI package demands that all later packages are also PyPI packages. +- Reasons for broken installations + - Using both `conda-forge` and `pytorch` channels, this can lead to conflicts. Choose one or the other. +- Not installing the GPU version of the `pytorch` package: + - Using [conda-forge](./#installing-from-conda-forge): Use the `system-requirements.cuda` to tell pixi to install the `cuda` packages. And set the `cuda-version` package to the version you want to install. + - Using [PyPI](./#installing-from-pypi): Make sure you are using the correct [index](./#pytorch-index) for the version you want to install. +- Not being able to solve the environment: +``` +├─▶ 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. +``` +This error occurs when the ABI tag of the Python version doesn't match the wheels available on PyPI. +Fix this by lowering the `requires-python` or `python` dependency. +At the time of writing Python 3.13 is not supported by PyTorch wheels yet. diff --git a/docs/reference/pixi_manifest.md b/docs/reference/pixi_manifest.md index 006d1b72f..bf2ffccc8 100644 --- a/docs/reference/pixi_manifest.md +++ b/docs/reference/pixi_manifest.md @@ -525,6 +525,7 @@ torch = { version = "*", index = "https://download.pytorch.org/whl/cu118" } ``` This is useful for PyTorch specifically, as the registries are pinned to different CUDA versions. +Learn more about installing PyTorch [here](../features/pytorch.md). ##### `git` diff --git a/docs/source_files/pixi_tomls/pytorch-conda-forge.toml b/docs/source_files/pixi_tomls/pytorch-conda-forge.toml new file mode 100644 index 000000000..1ce59bb27 --- /dev/null +++ b/docs/source_files/pixi_tomls/pytorch-conda-forge.toml @@ -0,0 +1,31 @@ +# --8<-- [start:minimal] +[project] +channels = ["conda-forge"] +name = "pytorch-conda-forge" +platforms = ["linux-64"] + +[system-requirements] +cuda = "12.0" + +# --8<-- [start:cuda-version] +[dependencies] +pytorch-gpu = "*" +# --8<-- [end:minimal] +cuda-version = "12.6" +# --8<-- [end:cuda-version] + +# --8<-- [start:use-envs] +[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"] +# --8<-- [start:use-envs] diff --git a/docs/source_files/pixi_tomls/pytorch-from-pytorch-channel.toml b/docs/source_files/pixi_tomls/pytorch-from-pytorch-channel.toml new file mode 100644 index 000000000..5be4f9b81 --- /dev/null +++ b/docs/source_files/pixi_tomls/pytorch-from-pytorch-channel.toml @@ -0,0 +1,16 @@ +# --8<-- [start:minimal] +[project] +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"] + +[feature.gpu.system-requirements] +cuda = "12.0" + +[dependencies] +pytorch = "*" + +[environments] +gpu = ["gpu"] +# --8<-- [end:minimal] diff --git a/docs/source_files/pixi_tomls/pytorch-pypi.toml b/docs/source_files/pixi_tomls/pytorch-pypi.toml new file mode 100644 index 000000000..11f89f9f6 --- /dev/null +++ b/docs/source_files/pixi_tomls/pytorch-pypi.toml @@ -0,0 +1,19 @@ +# --8<-- [start:minimal] +[project] +channels = ["https://prefix.dev/conda-forge"] +name = "pytorch-pypi" +platforms = ["osx-arm64", "linux-64"] + +[dependencies] +# We need a python version that is compatible with pytorch +python = ">=3.11,<3.13" + +[target.linux-64.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" } +# --8<-- [start:minimal] diff --git a/docs/source_files/pyproject_tomls/pytorch-conda-forge.toml b/docs/source_files/pyproject_tomls/pytorch-conda-forge.toml new file mode 100644 index 000000000..77ee829fb --- /dev/null +++ b/docs/source_files/pyproject_tomls/pytorch-conda-forge.toml @@ -0,0 +1,33 @@ +# --8<-- [start:minimal] +[project] +name = "pytorch-conda-forge" + +[tool.pixi.project] +channels = ["conda-forge"] +platforms = ["linux-64"] + +[tool.pixi.system-requirements] +cuda = "12.0" + +# --8<-- [start:cuda-version] +[tool.pixi.dependencies] +pytorch-gpu = "*" +# --8<-- [end:minimal] +cuda-version = "12.6" +# --8<-- [end:cuda-version] + +# --8<-- [start:use-envs] +[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"] +# --8<-- [start:use-envs] diff --git a/docs/source_files/pyproject_tomls/pytorch-from-pytorch-channel.toml b/docs/source_files/pyproject_tomls/pytorch-from-pytorch-channel.toml new file mode 100644 index 000000000..19485c959 --- /dev/null +++ b/docs/source_files/pyproject_tomls/pytorch-from-pytorch-channel.toml @@ -0,0 +1,20 @@ +# --8<-- [start:minimal] +[project] +name = "pytorch-from-pytorch-channel" +requires-python = ">= 3.11, < 3.13" +version = "0.1.0" + +[tool.pixi.project] +# `main` is not free! It's a paid channel for organizations over 200 people. +channels = ["main", "nvidia", "pytorch"] +platforms = ["osx-arm64", "linux-64"] + +[tool.pixi.feature.gpu.system-requirements] +cuda = "12.0" + +[tool.pixi.dependencies] +pytorch = "*" + +[tool.pixi.environments] +gpu = ["gpu"] +# --8<-- [end:minimal] diff --git a/docs/source_files/pyproject_tomls/pytorch-pypi.toml b/docs/source_files/pyproject_tomls/pytorch-pypi.toml new file mode 100644 index 000000000..2e4b4a622 --- /dev/null +++ b/docs/source_files/pyproject_tomls/pytorch-pypi.toml @@ -0,0 +1,19 @@ +# --8<-- [start:minimal] +[project] +name = "pytorch-pypi" +# We need a python version that is compatible with pytorch +requires-python = ">= 3.11,<3.13" + +[tool.pixi.project] +channels = ["https://prefix.dev/conda-forge"] +platforms = ["osx-arm64", "linux-64"] + +[tool.pixi.target.linux-64.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" } +# --8<-- [start:minimal] diff --git a/mkdocs.yml b/mkdocs.yml index 77d5b7d0e..cfe95be29 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -123,6 +123,7 @@ nav: - Lockfile: features/lockfile.md - System Requirements: features/system_requirements.md - Global Tools: features/global_tools.md + - Pytorch Installation: features/pytorch.md - Building Packages: - Getting started: build/getting_started.md - Dependency Types: build/dependency_types.md diff --git a/tests/integration_rust/project_tests.rs b/tests/integration_rust/project_tests.rs index 856d2d343..de1ce7929 100644 --- a/tests/integration_rust/project_tests.rs +++ b/tests/integration_rust/project_tests.rs @@ -127,6 +127,21 @@ fn parse_valid_docs_manifests() { } } } +#[test] +fn parse_valid_docs_pyproject_manifests() { + // Test all files in the docs/source_files/pyproject_tomls directory + let schema_dir = + PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("docs/source_files/pyproject_tomls"); + for entry in fs_err::read_dir(schema_dir).unwrap() { + let entry = entry.unwrap(); + let path = entry.path(); + if path.extension().map(|ext| ext == "toml").unwrap_or(false) { + let pyproject_toml = fs_err::read_to_string(&path).unwrap(); + let _project = + Project::from_str(&PathBuf::from("pyproject.toml"), &pyproject_toml).unwrap(); + } + } +} #[test] fn parse_valid_docs_configs() {