Skip to content

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.

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

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):

  1. recipe.yaml or recipe.yml in the same directory as the package manifest
  2. recipe/recipe.yaml or recipe/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:

  1. 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.

  2. 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").

  3. 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:

pixi.toml
[package.build-dependencies]
a = { path = "../a" }

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.

[package.build.configuration]
debug-dir = "debug-output"

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.

[package.build.configuration]
extra-input-globs = [
    "patches/**/*",
    "scripts/*.sh",
    "*.md"
]

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:

  1. Recipe Discovery: Locates the recipe.yaml file in standard locations
  2. Dependency Resolution: Resolves build, host, and run dependencies from conda channels and workspace
  3. Virtual Package Detection: Automatically detects system virtual packages
  4. Build Execution: Runs the build script specified in the recipe
  5. 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