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

Use optional dependencies with conflict rules and explicit package indexes in 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 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, 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 for dependency declaration, main.py for runtime verification, and README.md for documentation.

Optional Dependencies and Conflict Resolution

The configuration defines two mutually exclusive extras in pyproject.toml lines 24-27:

[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:

[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:

# 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 lines 38-50:

[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:

[[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 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:

# 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 (lines 25-31 and 33-40):

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 line 35:

[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 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 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, 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 (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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}