Skip to main content
Pixi is designed to work across all major platforms. When building applications that run on multiple operating systems or architectures, you need platform-specific configuration. This guide shows you how.

​
Platform Definition

Define supported platforms in your workspace: 
[workspace]
name = "my-app"
channels = ["conda-forge"]
platforms = ["win-64", "linux-64", "osx-64", "osx-arm64"]

​
Supported Platforms

  • linux-64 - Linux x86_64
  • linux-aarch64 - Linux ARM64
  • osx-64 - macOS Intel
  • osx-arm64 - macOS Apple Silicon
  • win-64 - Windows x86_64
Pixi determines which dependencies to install for each platform individually, storing everything in the lock file.

​
Platform Validation

Running pixi install on an unsupported platform shows a warning: 
pixi install
# WARN Not installing dependency for (default) on current platform: (osx-arm64)
# as it is not part of this project's supported platforms.

​
Target Specifiers

Use target specifiers to configure platform-specific settings. The [target.<platform>] section overrides default configuration for specific platforms.
You can only target platforms listed in workspace.platforms. Targeting unlisted platforms causes an error.

​
Platform-Specific Dependencies

Install different packages or versions per platform: 
[workspace]
platforms = ["win-64", "linux-64", "osx-64", "osx-arm64"]

[dependencies]
python = ">=3.8"

# Windows-only dependencies
[target.win-64.dependencies]
msmpi = "*"
python = "3.8"  # Overrides the >=3.8 requirement

# macOS ARM-only dependencies
[target.osx-arm64.dependencies]
mlx = ">=0.16.0"

# Linux-only dependencies
[target.linux-64.dependencies]
cuda = "12.1"
Platform-specific dependencies override (not merge with) the base dependencies for that package.

​
Using the CLI

Add platform-specific dependencies from the command line: 
# Add Windows-specific package
pixi add --platform win-64 msmpi

# Add macOS ARM-specific package
pixi add --platform osx-arm64 mlx

# Add Linux-specific build dependency
pixi add --build --platform linux-64 cuda
This generates: 
[target.win-64.dependencies]
msmpi = "1.0.0.*"

[target.osx-arm64.dependencies]
mlx = "0.16.0.*"

[target.linux-64.build-dependencies]
cuda = "12.1.*"

​
Host and Build Dependencies

Platform-specific dependencies work with host and build dependencies too: 
# Platform-specific host dependency
pixi add --host --platform win-64 posix

# Platform-specific build dependency
pixi add --build --platform osx-64 clang
Results in: 
[target.win-64.host-dependencies]
posix = "1.0.0.*"

[target.osx-64.build-dependencies]
clang = "16.0.6.*"

​
Platform-Specific Activation

Different platforms often require different activation scripts: 
[activation]
scripts = ["setup.sh", "local_setup.bash"]

[target.win-64.activation]
scripts = ["setup.bat", "local_setup.bat"]
On Windows, only the target.win-64.activation.scripts run - the base activation.scripts are replaced, not merged.

​
Activation Environment Variables

Set platform-specific environment variables: 
[activation.env]
DEFAULT_PATH = "/usr/local"

[target.win-64.activation.env]
DEFAULT_PATH = "C:\\Program Files"

[target.osx-arm64.activation.env]
DEFAULT_PATH = "/opt/homebrew"

​
Platform-Specific System Requirements

Define different system requirements per platform: 
[system-requirements]
linux = "4.18"

[target.linux-64.system-requirements]
cuda = "12.1"

[target.osx-arm64.system-requirements]
macos = "13.5"

​
Complete Example

Here’s a real-world multi-platform configuration: 
[workspace]
name = "cross-platform-app"
channels = ["conda-forge"]
platforms = ["win-64", "linux-64", "osx-64", "osx-arm64"]

# Base dependencies for all platforms
[dependencies]
python = ">=3.8"
numpy = ">=1.21"

# Windows-specific configuration
[target.win-64.dependencies]
python = "3.8"  # Windows needs specific version
msmpi = "*"     # Windows MPI implementation

[target.win-64.activation]
scripts = ["setup.bat"]

[target.win-64.activation.env]
COMPILER = "msvc"

# Linux-specific configuration
[target.linux-64.dependencies]
openmpi = "*"  # Linux MPI implementation

[target.linux-64.system-requirements]
linux = "4.18"
libc = { family = "glibc", version = "2.28" }

[target.linux-64.activation]
scripts = ["setup.sh"]

[target.linux-64.activation.env]
COMPILER = "gcc"

# macOS Intel configuration
[target.osx-64.dependencies]
clang = ">=14"

[target.osx-64.activation]
scripts = ["setup.sh"]

# macOS ARM configuration
[target.osx-arm64.dependencies]
mlx = ">=0.16.0"  # Apple Silicon ML framework

[target.osx-arm64.system-requirements]
macos = "13.0"  # Minimum macOS version

[target.osx-arm64.activation]
scripts = ["setup.sh"]

[target.osx-arm64.activation.env]
COMPILER = "clang"
ARCH = "arm64"

# Shared activation for Unix-like systems
[activation]
scripts = ["setup.sh"]

[activation.env]
PROJECT_ROOT = "$PIXI_PROJECT_ROOT"

​
Multi-Platform with Multiple Environments

Combine platform targeting with multiple environments: 
[workspace]
name = "ml-project"
channels = ["conda-forge", "pytorch", "nvidia"]
platforms = ["linux-64", "osx-arm64"]

[dependencies]
python = "3.11.*"
pytorch = { version = ">=2.0.1", channel = "pytorch" }

# CUDA feature for Linux
[feature.cuda]
platforms = ["linux-64"]  # CUDA only on Linux
system-requirements = { cuda = "12.1" }

[feature.cuda.dependencies]
pytorch-cuda = { version = "12.1.*", channel = "pytorch" }

# MLX feature for macOS ARM
[feature.mlx]
platforms = ["osx-arm64"]  # MLX only on Apple Silicon

[feature.mlx.dependencies]
mlx = ">=0.16.0"

[environments]
cuda = ["cuda"]  # Only resolves on linux-64
mlx = ["mlx"]    # Only resolves on osx-arm64
Usage: 
# On Linux with CUDA
pixi run --environment cuda train-model

# On macOS ARM with MLX
pixi run --environment mlx train-model

# Error on wrong platform
# pixi run --environment cuda train-model
# Error: cuda environment not available on osx-arm64

​
Best Practices

Define All Target Platforms 
[workspace]
# Be explicit about supported platforms
platforms = ["linux-64", "osx-arm64", "win-64"]
Use Platform-Specific Activation 
# Base script for Unix-like systems
[activation]
scripts = ["setup.sh"]

# Override for Windows
[target.win-64.activation]
scripts = ["setup.bat"]
Test on All Platforms 
# .github/workflows/test.yml
strategy:
  matrix:
    os: [ubuntu-latest, macos-latest, windows-latest]
steps:
  - run: pixi install --frozen
  - run: pixi run test
Document Platform Requirements 
# README.md should mention:
# - Supported platforms
# - Platform-specific system requirements
# - Platform-specific features
Cross-Platform Python
[dependencies]
python = ">=3.8"
numpy = "*"
Platform-Specific Compilers
[target.linux-64.dependencies]
gcc = "*"

[target.osx-64.dependencies]
clang = "*"

[target.win-64.dependencies]
vs2019_win-64 = "*"
Hardware Acceleration
[target.linux-64.dependencies]
cuda = "12.1"
cudnn = "8.*"

[target.osx-arm64.dependencies]
mlx = "*"  # Apple Silicon ML