docs: add pytorch integration guide.

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.

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`
 

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]

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]

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]

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]

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]

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]

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

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() {