Building Python Packages

Create conda packages from Python projects using pixi-build-python

Learn how to build Python packages with Pixi, leveraging the conda ecosystem’s cross-language capabilities.

pixi-build is a preview feature and will change until stabilized. Keep this in mind for production projects.

Why Build Python Packages with Pixi?

Building Python packages with Pixi offers unique advantages:

1. Cross-language support - Manage Python packages alongside Rust, C++, R, and other languages
2. Unified tooling - Build both conda and Python packages with the same tool
3. Conda ecosystem - Access packages from conda-forge, not just PyPI
4. Workspace support - Develop multiple interdependent packages together

Creating Your First Python Package

You should see:

┏━━━━━━━━━━━━━━┳━━━━━┳━━━━━━━━━━━━━┓
┃ name         ┃ age ┃ city        ┃
┡━━━━━━━━━━━━━━╇━━━━━╇━━━━━━━━━━━━━┩
│ John Doe     │ 30  │ New York    │
│ Jane Smith   │ 25  │ Los Angeles │
│ Tim de Jager │ 35  │ Utrecht     │
└──────────────┴─────┴─────────────┘

Advanced Configuration

Using Custom Backend Channels

For the latest backend features:

[package.build.backend]
channels = [
  "https://prefix.dev/pixi-build-backends",
  "https://prefix.dev/conda-forge",
]
name = "pixi-build-python"
version = "0.4.*"

Noarch Packages

For pure Python packages without compiled extensions:

[package.build.config]
noarch = true

This creates a single package that works across all platforms.

Custom Build Configuration

Editable Installs

[package.build.config]
editable = true

Real-World Example

Here’s a complete example from the array-api-extra package:

pixi.toml

[workspace]
channels = ["https://prefix.dev/conda-forge"]
name = "array-api-extra-build"
platforms = ["osx-arm64", "linux-64", "osx-64", "win-64"]
preview = ["pixi-build"]
version = "0.1.0"

[dependencies]
array-api-extra = { path = "." }

[tasks]
test = "python -c 'import array_api_extra'"

[package]
name = "array-api-extra"
version = "0.8.0"

[package.build.backend]
channels = [
  "https://prefix.dev/pixi-build-backends",
  "https://prefix.dev/conda-forge",
]
name = "pixi-build-python"
version = "0.4.*"

Understanding Host vs Run Dependencies

Why specify dependencies twice?

Python packages need to declare dependencies in two places:

In pyproject.toml (for PyPI):

[project]
dependencies = ["rich"]

In pixi.toml (for conda):

[package.run-dependencies]
rich = "13.9.*"

This allows the same package to work in both ecosystems.

What are host-dependencies?

Host dependencies are needed during the build process. For Python:

[package.host-dependencies]
hatchling = "*"  # Build backend
uv = "*"          # Optional: faster installer
python = "3.11.*" # Python version for building

These come from conda channels, ensuring consistent build environments.

See dependency types for details.

Integration with pyproject.toml

You can integrate Pixi configuration into pyproject.toml:

pyproject.toml

[project]
name = "python_rich"
version = "0.1.0"
requires-python = ">= 3.11"
dependencies = ["rich"]

[build-system]
build-backend = "hatchling.build"
requires = ["hatchling"]

[tool.pixi.workspace]
channels = ["https://prefix.dev/conda-forge"]
platforms = ["linux-64", "osx-64", "osx-arm64", "win-64"]
preview = ["pixi-build"]

[tool.pixi.dependencies]
python_rich = { path = "." }

[tool.pixi.package]
name = "python_rich"
version = "0.1.0"

[tool.pixi.package.build]
backend = { name = "pixi-build-python", version = "0.4.*" }

Next Steps

Workspaces

Combine multiple packages in one workspace

Dependency Types

Understand build, host, and run dependencies

C++ Integration

Mix Python with C++ packages

Build Variants

Build against multiple Python versions

Common Issues

Technical Limitation: Dependencies like hatchling, pip, and uv must be in host-dependencies (not build-dependencies) due to how the build process currently works. This ensures the correct Python prefix is used.

Package not found after build

Ensure your package is added to workspace dependencies:

[dependencies]
your_package = { path = "." }

Import errors at runtime

Add missing dependencies to run-dependencies:

[package.run-dependencies]
missing_package = "*"