Rattler-Build Backend#
The pixi-build-rattler-build
backend enables building conda packages using rattler-build recipes.
This backend is designed for projects that either have existing recipe.yaml files or where customization is necessary that isn't possible with the currently available backends.
Warning
pixi-build
is a preview feature, and will change until it is stabilized.
This is why we require users to opt in to that feature by adding "pixi-build" to workspace.preview
.
Overview#
The rattler-build backend:
- Uses existing
recipe.yaml
files as build manifests - Supports all standard rattler-build recipe features and selectors
- Handles dependency resolution and virtual package detection automatically
- Can build multiple outputs from a single recipe
Usage#
To use the rattler-build backend in your pixi.toml
, specify it in your build system configuration:
[package]
name = "rattler_build_package"
version = "0.1.0"
[package.build]
backend = { name = "pixi-build-rattler-build", version = "*" }
channels = ["https://prefix.dev/conda-forge"]
The backend expects a rattler-build recipe file in one of these locations (searched in order):
recipe.yaml
orrecipe.yml
in the same directory as the package manifestrecipe/recipe.yaml
orrecipe/recipe.yml
in a subdirectory of the package manifest
If the package is defined in the same location as the workspace, it is heavily encouraged to place the recipe file in its own directory recipe
.
Learn more about the rattler-build
, and its recipe format in its high level overview.
Specifying dependencies#
We only allow source dependencies (workspace packages) in project manifest.
Binary dependencies are not allowed in the project manifest when using pixi-build-rattler-build
.
This is intentional because:
-
The rattler-build recipe is the source of truth for binary dependencies. It already specifies exact versions, build variants, and whether dependencies go in build/host/run.
-
Allowing binary dependencies in both places would create duplication and potential conflicts (e.g., recipe says "python >=3.10" but project model says "python >=3.9").
-
Source dependencies are different - they represent workspace packages built from local source. The recipe can reference them by name, but can't know their workspace paths. The project model provides this mapping.
This way, the recipe maintains full control over binary dependencies while the project model only provides the workspace structure information that the recipe cannot know.
To specify source dependencies, add them to build-dependencies
, host-dependencies
or run-dependencies
in the package manifest:
Configuration Options#
The rattler-build backend supports the following TOML configuration options:
debug-dir
#
- Type:
String
(path) - Default: Not set
- Target Merge Behavior: Not allowed - Cannot have target specific value
If specified, internal build state and debug information will be written to this directory. Useful for troubleshooting build issues.
extra-input-globs
#
- Type:
Array<String>
- Default:
[]
- Target Merge Behavior:
Overwrite
- Platform-specific globs completely replace base globs
Additional glob patterns to include as input files for the build process. These patterns are added to the default input globs that are determined from the recipe sources and package directory structure.
For target-specific configuration, platform-specific globs completely replace the base:
[package.build.configuration]
extra-input-globs = ["*.yaml", "*.md"]
[package.build.configuration.targets.linux-64]
extra-input-globs = ["*.yaml", "*.md", "*.sh", "patches-linux/**/*"]
# Result for linux-64: ["*.yaml", "*.md", "*.sh", "patches-linux/**/*"]
Build Process#
The rattler-build backend follows this build process:
- Recipe Discovery: Locates the
recipe.yaml
file in standard locations - Dependency Resolution: Resolves build, host, and run dependencies from conda channels and workspace
- Virtual Package Detection: Automatically detects system virtual packages
- Build Execution: Runs the build script specified in the recipe
- Package Creation: Creates conda packages according to the recipe specification
Limitations#
- Requires an existing rattler-build recipe file - cannot infer build instructions automatically
- Build configuration is primarily controlled through the recipe file rather than
pixi.toml
- Cannot specify binary dependencies in the manifest