Skip to main content
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

1
Enable the Preview Feature
2
Since pixi-build is in preview, you must enable it explicitly:
3
[workspace]
preview = ["pixi-build"]
4
The [workspace] section is currently an alias for [project] and specifies properties shared across all packages like name, channels, and platforms.
5
Define Your Package
6
The [package] section specifies properties for the package you want to build:
7
[package]
name = "python_rich"
version = "0.1.0"
8
Configure the Build Backend
9
Specify which build backend to use and where to download it from:
10
[package.build]
backend = { name = "pixi-build-python", version = "0.4.*" }
11
Build backends describe how to build a conda package for a specific language or build tool. See the backends overview for available options.
12
Add Host Dependencies
13
Host dependencies are needed during the build process. For Python packages using PEP 517 backends:
14
[package.host-dependencies]
hatchling = "==1.26.3"
15
The Python build backend (like hatchling) knows how to build a Python package, and pixi-build-python converts it into a conda package.
16
Learn more about dependency types.
17
Specify Run Dependencies
18
Add packages needed at runtime:
19
[package.run-dependencies]
rich = "13.9.*"
20
Add as Workspace Dependency
21
Include your package in the workspace dependencies:
22
[dependencies]
python_rich = { path = "." }

​
CLI Commands

Once configured, you can use these commands: 
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

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.*"
Check that:
  1. All dependencies are available in your specified channels
  2. Platform specifications match your target platforms
  3. Version constraints are compatible
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>/