Getting Started with Building Packages

Learn how to build conda packages from source with Pixi

Pixi can build packages from source in addition to managing workflows and environments. This enables you to:

• Build and upload packages to conda channels
• Allow users to depend directly on source code that builds automatically
• Manage multiple packages in a workspace
• Create cross-language projects with unified tooling

The pixi-build feature is currently in preview and has some limitations:

1. Limited set of build backends
2. Build backends may be missing some parameters/features
3. Recursive source dependencies are not yet supported
4. Workspace dependencies cannot be inherited

Quick Start

Here’s a complete example of a buildable Python package:

pixi.toml

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

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

[tasks]
start = "rich-example-main"

[package]
name = "python_rich"
version = "0.1.0"

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

[package.host-dependencies]
hatchling = "==1.26.3"

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

Understanding the Manifest Structure

CLI Commands

Once configured, you can use these commands:

Build a Package

pixi build

• pixi build creates a .conda file from your package
• Commands like pixi install and pixi run automatically build packages when a path, git, or url dependency is present

Complete Example Structure

Here’s what a complete project looks like:

python_rich/
├── pixi.toml           # Pixi manifest
├── pyproject.toml      # Python project metadata
├── .gitignore
└── src/
    └── python_rich/
        └── __init__.py # Package code

Next Steps

Python Packages

Build Python packages with pixi-build-python

C++ Packages

Build C++ packages with CMake

Workspaces

Manage multiple packages together

Build Backends

Explore available build backends

Troubleshooting

Build fails with 'backend not found'

Make sure you’ve enabled the preview feature and specified the correct backend channels:

[workspace]
preview = ["pixi-build"]

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

Dependencies not resolving

Check that:

1. All dependencies are available in your specified channels
2. Platform specifications match your target platforms
3. Version constraints are compatible

Need to see the generated recipe?

Recipes are stored in .pixi/build/work/<package-name>--<hash>/debug/recipe/

You can rebuild using:

rattler-build build --recipe .pixi/build/work/<package-name>--<hash>/debug/recipe/<variant_hash>/