# Platform-Specific PyTorch Installation Strategies with uv: A Complete Guide to sys_platform and os_name Configuration

> Master platform-specific PyTorch installation with uv. Learn to configure sys_platform and os_name in pyproject.toml for seamless CPU-only and CUDA builds. Optimize your environment-specific constraints.

- Repository: [Th3Unknovvn/uv-install-torch](https://github.com/baonguyen6742/uv-install-torch)
- Tags: tutorial
- Published: 2026-02-26

---

**Use optional dependencies with conflict rules and explicit package indexes in [`pyproject.toml`](https://github.com/baonguyen6742/uv-install-torch/blob/main/pyproject.toml) to declaratively manage CPU-only and CUDA-enabled PyTorch builds while leveraging `sys_platform` and `os_name` markers for environment-specific constraints.**

The `baonguyen6742/uv-install-torch` repository demonstrates a production-ready approach to managing PyTorch installations across different platforms using uv's advanced dependency resolution. By combining optional dependencies with platform markers and explicit package indexes, you can create a single [`pyproject.toml`](https://github.com/baonguyen6742/uv-install-torch/blob/main/pyproject.toml) that supports both CPU-only and CUDA-enabled PyTorch configurations without version conflicts.

## Understanding Platform-Specific PyTorch Installation with uv

Traditional PyTorch installation requires manual management of CUDA versions, platform-specific wheel URLs, and virtual environments. The uv package manager solves this through declarative configuration in [`pyproject.toml`](https://github.com/baonguyen6742/uv-install-torch/blob/main/pyproject.toml), allowing you to define multiple installation profiles using **optional dependencies** (extras) and **platform markers** (`sys_platform`, `os_name`).

This approach eliminates manual index URL management and prevents common errors like installing both CPU and CUDA wheels simultaneously.

## Core Architecture and Configuration Files

The implementation centers on three files in the `baonguyen6742/uv-install-torch` repository: [`pyproject.toml`](https://github.com/baonguyen6742/uv-install-torch/blob/main/pyproject.toml) for dependency declaration, [`main.py`](https://github.com/baonguyen6742/uv-install-torch/blob/main/main.py) for runtime verification, and [`README.md`](https://github.com/baonguyen6742/uv-install-torch/blob/main/README.md) for documentation.

### Optional Dependencies and Conflict Resolution

The configuration defines two mutually exclusive extras in [`pyproject.toml`](https://github.com/baonguyen6742/uv-install-torch/blob/main/pyproject.toml) lines 24-27:

```toml
[project.optional-dependencies]
cpu = ["torch", "torchvision", "torchaudio"]
cu124 = ["torch", "torchvision", "torchaudio"]

```

To prevent both from being installed simultaneously, a **conflict rule** is declared at line 32:

```toml
[tool.uv.conflicts]
extra = [
    { extra = "cpu" },
    { extra = "cu124" },
]

```

This ensures `uv sync` fails if a user attempts to activate both extras, maintaining environment consistency.

### Platform Constraints with sys_platform and os_name

While the example keeps it commented for demonstration purposes, line 35 shows how to restrict the entire installation to specific platforms:

```toml

# environments = ["sys_platform == 'linux' and os_name == 'posix'"]

```

When uncommented, this **environment marker** prevents `uv sync` from executing on non-Linux systems, ensuring CUDA-dependent projects don't install on incompatible Windows or macOS machines. The `sys_platform` variable corresponds to Python's `sys.platform` (returning values like `"linux"`, `"darwin"`, or `"win32"`), while `os_name` corresponds to `os.name` (returning `"posix"` for Unix-like systems and `"nt"` for Windows).

### Custom Package Indexes in tool.uv.sources

The critical mapping between extras and PyTorch's platform-specific wheels occurs in [`pyproject.toml`](https://github.com/baonguyen6742/uv-install-torch/blob/main/pyproject.toml) lines 38-50:

```toml
[tool.uv.sources]
torch = [
  { index = "pytorch-cpu", extra = "cpu", marker = "platform_machine == 'x86_64'" },
  { index = "pytorch-cu124", extra = "cu124" },
]
torchvision = [
  { index = "pytorch-cpu", extra = "cpu", marker = "platform_machine == 'x86_64'" },
  { index = "pytorch-cu124", extra = "cu124" },
]
torchaudio = [
  { index = "pytorch-cpu", extra = "cpu", marker = "platform_machine == 'x86_64'" },
  { index = "pytorch-cu124", extra = "cu124" },
]

```

This configuration directs uv to pull packages from `pytorch-cpu` when the `cpu` extra is selected, and from `pytorch-cu124` when `cu124` is selected.

The actual index URLs are defined in lines 53-62:

```toml
[[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

```

The **`explicit = true`** flag ensures uv only queries these indexes for the packages explicitly mapped to them, preventing these large repositories from slowing down resolution of unrelated dependencies.

## Step-by-Step Implementation

### Configuring pyproject.toml for CPU and CUDA Builds

To implement this strategy in your own project, structure your [`pyproject.toml`](https://github.com/baonguyen6742/uv-install-torch/blob/main/pyproject.toml) with three key sections:

1. **Base dependencies** with optional extras for each platform/GPU combination
2. **Conflict rules** to prevent multiple extras
3. **Source mappings** linking extras to specific package indexes

### Installing Platform-Specific PyTorch Versions

With the configuration in place, installation becomes a single command:

```bash

# Install CPU-only PyTorch

uv sync --extra cpu

# Install CUDA 12.4 PyTorch

uv sync --extra cu124

```

uv automatically resolves the correct wheels from the specified indexes based on your platform (Linux, Windows, macOS) and the selected extra.

### Runtime Verification with main.py

After installation, verify the correct variant was installed using the runtime detection logic in [`main.py`](https://github.com/baonguyen6742/uv-install-torch/blob/main/main.py) (lines 25-31 and 33-40):

```python
import torch
import sys
import platform
import os

def check_installation():
    # Display platform information

    print("Python:", sys.version.split()[0])
    print("sys_platform:", sys.platform)
    print("os_name:", os.name)
    print("platform_system:", platform.system())
    
    # Verify PyTorch installation

    print("torch version:", torch.__version__)
    print("CUDA available:", torch.cuda.is_available())
    
    if torch.cuda.is_available():
        for i in range(torch.cuda.device_count()):
            props = torch.cuda.get_device_properties(i)
            print(f"Device {i}: {props.name} ({props.total_memory / 1e9:.1f} GB)")
    else:
        print("Running on CPU")

if __name__ == "__main__":
    check_installation()

```

This script confirms that `sys.platform`, `os.name`, and `torch.cuda.is_available()` align with your intended installation target.

## Advanced Platform Filtering Techniques

### Restricting Installation to Linux Only

For projects that require CUDA support only available on Linux, uncomment the environment constraint in [`pyproject.toml`](https://github.com/baonguyen6742/uv-install-torch/blob/main/pyproject.toml) line 35:

```toml
[tool.uv]
environments = ["sys_platform == 'linux' and os_name == 'posix'"]

```

With this configuration, `uv sync` will fail on Windows or macOS with a clear error message, preventing accidental installation attempts on unsupported platforms. This is particularly valuable for ML training pipelines that depend on Linux-specific CUDA drivers.

## Summary

- **Declarative configuration** in [`pyproject.toml`](https://github.com/baonguyen6742/uv-install-torch/blob/main/pyproject.toml) eliminates manual wheel selection by using optional dependencies (`cpu` and `cu124`) with conflict rules to ensure mutual exclusivity.
- **Platform markers** (`sys_platform`, `os_name`) allow you to restrict installations to specific operating systems when necessary, preventing incompatible CUDA installs on Windows or macOS.
- **Explicit package indexes** in `[tool.uv.sources]` map extras to PyTorch's CPU or CUDA wheel repositories without polluting the global package index.
- **Single-command installation** via `uv sync --extra cpu` or `uv sync --extra cu124` automatically resolves the correct platform-specific wheels.
- **Runtime verification** using `torch.cuda.is_available()` in [`main.py`](https://github.com/baonguyen6742/uv-install-torch/blob/main/main.py) confirms whether CPU or CUDA variants were installed correctly.

## Frequently Asked Questions

### What is the difference between sys_platform and os_name in uv configuration?

**`sys_platform`** refers to the value of Python's `sys.platform` variable, which typically returns strings like `"linux"`, `"darwin"` (macOS), or `"win32"`. **`os_name`** corresponds to `os.name`, returning `"posix"` for Unix-like systems (Linux, macOS) and `"nt"` for Windows. In [`pyproject.toml`](https://github.com/baonguyen6742/uv-install-torch/blob/main/pyproject.toml), you can combine these markers—such as `sys_platform == "linux" and os_name == "posix"`—to create precise platform filters that prevent installation on incompatible systems.

### How do I prevent both CPU and CUDA PyTorch versions from installing simultaneously?

The repository uses **conflict rules** defined in the `[tool.uv.conflicts]` section of [`pyproject.toml`](https://github.com/baonguyen6742/uv-install-torch/blob/main/pyproject.toml) (line 32). By declaring `extra = [{ extra = "cpu" }, { extra = "cu124" }]`, uv treats these extras as mutually exclusive. If you attempt to run `uv sync --extra cpu --extra cu124`, the command will fail with a conflict error, ensuring your environment contains only one PyTorch variant and preventing runtime errors from mixed wheel installations.

### Can I use uv to install PyTorch on Windows or macOS with the same configuration?

Yes, the configuration supports cross-platform installation, but with important caveats. The [`pyproject.toml`](https://github.com/baonguyen6742/uv-install-torch/blob/main/pyproject.toml) in `baonguyen6742/uv-install-torch` uses explicit indexes pointing to PyTorch's official repositories, which provide wheels for Linux, Windows, and macOS. However, the **CUDA extras** (`cu124`) are primarily supported on Linux. If you uncomment the platform restriction (`environments = ["sys_platform == 'linux' and os_name == 'posix'"]`), uv will block installation on Windows and macOS. For cross-platform projects, remove that restriction and use the `cpu` extra, which works uniformly across all platforms.

### Why does uv require explicit package indexes for PyTorch installation?

PyTorch distributes platform-specific wheels (CPU vs. CUDA) through separate repository URLs (`https://download.pytorch.org/whl/cpu` and `https://download.pytorch.org/whl/cu124`). By setting **`explicit = true`** in the `[[tool.uv.index]]` declarations (lines 53-62), you prevent uv from searching these indexes for unrelated packages, which speeds up resolution and avoids conflicts with PyPI. The `[tool.uv.sources]` section then maps specific extras to these indexes, ensuring uv only downloads PyTorch wheels from the correct repository based on whether you selected `--extra cpu` or `--extra cu124`.