Skip to content

docs: document the build variants pixi sets automatically #6534

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Hofer-Julian merged 1 commit into from
Jul 9, 2026
+32 −4
Merged

docs: document the build variants pixi sets automatically #6534

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 26 additions & 0 deletions docs/build/variants.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -90,6 +90,32 @@ python_rich 0.1.0 pyhbf21a9e_0 conda python_rich
```


## Variants Pixi Sets for You

Not every variant has to be spelled out in `[workspace.build-variants]`.
When you build a package, Pixi fills in a few variants automatically based on the platform you build for and its [system requirements](../workspace/system_requirements.md).
An explicit `[workspace.build-variants]` entry always wins over a value Pixi derives, so you can override any of these by hand.

### `target_platform`

Every build is tagged with the platform it is built for, so a build made for `linux-64` and one made for `osx-arm64` stay distinct.
You never set this yourself; it comes from the platform being built.

### `c_stdlib` and `c_stdlib_version`

Build backends pin the minimum OS/libc target through the recipe's `stdlib("c")` function, which resolves against the `c_stdlib` and `c_stdlib_version` variants.
Rather than making you repeat this in `[workspace.build-variants]`, Pixi derives the pair from the target platform's system requirements (recorded as the `__osx` and `__glibc` virtual packages):

| Subdir | Virtual package | `c_stdlib` | `c_stdlib_version` |
|-----------|-----------------|----------------------------|------------------------|
| `osx-*` | `__osx` | `macosx_deployment_target` | the `__osx` version |
| `linux-*` | `__glibc` | `sysroot` | the `__glibc` version |

Platforms declared as a bare subdir string carry Pixi's portable defaults (`__glibc = "2.28"`, `__osx = "13.0"`), so the derivation works even when you don't declare system requirements explicitly.

The providers `macosx_deployment_target` and `sysroot` are conda-forge packages, so this derivation only applies when one of your channels is conda-forge.
It is skipped on Windows (which has no meaningful stdlib version), and musl (`__musl`) and CUDA (`__cuda`) are not derived yet.

## Conclusion

In this tutorial, we showed how to use variants to build multiple versions of a single package.
Expand Down
10 changes: 6 additions & 4 deletions docs/reference/pixi_manifest.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -218,7 +218,7 @@ internal = false
```

Mapping files are JSON objects with `conda_name: pypi_package_name` entries.
The value can also be a list of PyPI names — the conda package then satisfies all of them and one PURL is emitted per name — or `null` to mark a package as not available on PyPI.
The value can also be a list of PyPI names (the conda package then satisfies all of them and one PURL is emitted per name), or `null` to mark a package as not available on PyPI.
This is the same format that parselmouth publishes under [`files/v0/<channel>/compressed_mapping.json`](https://github.com/prefix-dev/parselmouth/tree/main/files/v0), so those files can be used directly (use the raw file URL).

```json title="local/robostack_mapping.json"
Expand Down Expand Up @@ -450,6 +450,8 @@ When build variants are specified, Pixi will:
3. **Resolve dependencies**: Ensure each variant resolves with compatible dependency versions
4. **Generate unique build strings**: Each variant gets a unique build identifier in the package name

On top of the variants you declare, Pixi fills in some automatically: `target_platform`, and (for conda-forge builds) `c_stdlib`/`c_stdlib_version` derived from the platform's [system requirements](../workspace/system_requirements.md). An explicit entry here always overrides a derived value. See [Variants Pixi Sets for You](../build/variants.md#variants-pixi-sets-for-you).

#### Platform-Specific Variants

Build variants can also be specified per-platform:
Expand Down Expand Up @@ -489,7 +491,7 @@ For detailed examples and tutorials, see the [build variants documentation](../b

Use `build-variants-files` to reference external variant definitions from YAML files.
Paths are resolved relative to the workspace root and processed in the listed
order—entries from earlier files take precedence over values loaded from later ones.
order: entries from earlier files take precedence over values loaded from later ones.

```toml
[workspace]
Expand All @@ -508,9 +510,9 @@ Otherwise, it will use `rattler-build`'s syntax as outlined in the [rattler-buil

!!! warning "Preview Feature"
`[workspace.dependencies]` requires the `pixi-build` preview feature to be
enabled and only applies to **package** dependencies — see
enabled and only applies to **package** dependencies (see
[Workspace Dependencies](../build/workspace_dependencies.md) for the
semantics, override rules and error cases.
semantics, override rules and error cases).

A pool of conda dependency specs that members of the workspace can inherit
per entry by writing `{ workspace = true }` in any of their
Expand Down