feat(publish): add `--variant` and `--variant-config` flags by wolfv · Pull Request #6109 · prefix-dev/pixi

wolfv · 2026-05-13T08:57:51Z

Description

Adds two new flags to pixi publish so callers can narrow the build matrix from the command line. This is the missing piece for parallelizing a package across its build variants in CI — today pixi publish always builds the full matrix.

The flags mirror the equivalent options on rattler-build:

--variant KEY=VAL[,VAL...] (repeatable) — overrides matching keys from the workspace's [workspace.build-variants]. Repeated uses of the same key accumulate values, but as a group they replace whatever the workspace had for that key. Other workspace keys are left untouched, so passing --variant python=3.12 against a workspace with python = [3.10, 3.11, 3.12] and cuda-version = [12.8, 13.0] still produces both CUDA variants — just only for Python 3.12.
--variant-config FILE / -m FILE (repeatable) — appends extra variant-config YAML files after the workspace's build-variants-files. Relative paths resolve against the current working directory.

Example from the issue:

pixi publish --variant python=3.12 --variant cuda-version=12.8,13.0
pixi publish -m variants.yaml

The deprecated pixi build command is intentionally left alone — it'll be redesigned separately.

Fixes #4877

How Has This Been Tested?

Added unit tests in crates/pixi_cli/src/publish.rs covering:
- parse_variant success paths (single value, comma-separated values, value containing =)
- parse_variant rejection of malformed input (missing =, empty key, empty value)
- overlay_cli_variants replacing the matching workspace key, accumulating repeated --variant flags for the same key, and leaving unrelated keys alone
cargo check -p pixi_cli and cargo check -p pixi --tests pass.
cargo test -p pixi_cli --lib publish:: — 3/3 pass.
cargo fmt / cargo clippy weren't available in the pinned 1.94.0 toolchain in the dev environment; please run them in CI.

AI Disclosure

This PR contains AI-generated content.
- I have tested any AI-generated content in my PR.
- I take responsibility for any AI-generated content in my PR.

Tools: Claude Code

Checklist:

I have performed a self-review of my own code
I have commented my code, particularly in hard-to-understand areas
I have made corresponding changes to the documentation
I have added sufficient tests to cover my changes.
I have verified that changes that would impact the JSON schema have been made in schema/model.py.

Generated by Claude Code

Lets callers narrow the build matrix from the command line so packages can be parallelized across variants in CI. CLI overrides replace matching keys from the workspace `build-variants`, while `--variant-config` files are appended to the workspace `build-variants-files`. Closes #4877.

Collapse parse_variant cases into success/error tables, replace the duplicate merge helper with a real overlay_cli_variants function used by execute().

baszalmstra · 2026-05-13T09:02:01Z

--variant-config FILE / -m FILE (repeatable) — appends extra variant-config YAML files after the workspace's build-variants-files. Relative paths resolve against the current working directory.

Does this also overwrite existing keys if there is a conflict?

baszalmstra · 2026-05-13T09:04:14Z

+/// Overlay CLI `--variant` overrides on top of the workspace variants.
+/// Multiple `--variant` flags with the same key accumulate values, but as a
+/// group they replace the matching key from the workspace.
+fn overlay_cli_variants(


I would prefer to return instead of having a mutable value.

Maybe we can have a function that creates a BTreeMap from the arguments and then justs use variant_configuration.extend at the callsite?

baszalmstra · 2026-05-13T09:07:29Z

+        assert_eq!(
+            parse_variant("expr=a=b").unwrap(),
+            ("expr".into(), vec!["a=b".into()]),
+        );


This seems like a mistake? Shouldnt that error?

baszalmstra · 2026-05-13T09:07:54Z

+    }
+
+    #[test]
+    fn overlay_cli_variants_replaces_workspace_key_and_accumulates_repeats() {


Should we also have tests for variant files?

baszalmstra

Missing docs.

Address review feedback on #6109: - Replace the &mut overlay helper with cli_variants_map() that returns a BTreeMap, used via variant_configuration.extend() at the callsite. - Reject `=` in variant values so typos like `python=3.12=foo` fail loudly instead of producing a single weird value. - Extract variant-config path resolution into resolve_variant_config_paths() and add a unit test for it. - Regenerate the autogenerated CLI docs for `pixi publish`. - Add example sections to publish_extender covering single-variant builds and `-m` files.

wolfv · 2026-05-13T09:19:55Z

Yes — when keys collide, the CLI-supplied -m file wins. The path ordering passed to the build backend is workspace build-variants-files first, then CLI --variant-config files. rattler_build_variant_config::VariantConfig::merge extends with other, so later files replace earlier values for the same key (the comment on that function calls this out: "Variant values are replaced (not merged)"). CLI --variant KEY=VAL overrides are applied on top of that in pixi publish itself, so they win against any file.

I documented this in publish_extender in 01db443.

Generated by Claude Code

wolfv · 2026-05-13T09:24:01Z

 pixi publish https://prefix.dev/my-channel --clean
 ```

+### Building a single variant (parallelizing CI)


The parallelziing CI is just one use case for this. We should not mention it as prominent.

Reframed in 846d0e3 — merged the two variant sections into a single "Overriding build variants" section and moved CI parallelization into a list of motivations in the intro rather than the heading.

Generated by Claude Code

@wolfv

Per @wolfv's review on #6109: parallelizing CI is one application of --variant, not the headline use case. Merge the two variant sections into a single 'Overriding build variants' section that lists the broader motivation and demotes CI parallelization to a phrase in the intro.

wolfv · 2026-05-13T09:24:35Z

+
+CLI overrides replace the matching key from the workspace `build-variants`; workspace keys that aren't named on the command line keep their full value list.
+
+### Providing additional variant config files


I think we can mention that it is preferred to mention the variant config files int he pixi.toml

Good call — done in 2ea6595. The paragraph now leads with "prefer listing the YAML files in [workspace.build-variants-files] in pixi.toml" and frames -m as the one-off-override path.

Generated by Claude Code

@wolfv

Per @wolfv on #6109: variant-config files should live in [workspace.build-variants-files] in pixi.toml so all contributors and CI runs pick them up. `--variant-config` / `-m` is for one-off overrides only.

claude added 2 commits May 13, 2026 08:06

test(publish): tighten variant tests and extract overlay helper

3902661

Collapse parse_variant cases into success/error tables, replace the duplicate merge helper with a real overlay_cli_variants function used by execute().

baszalmstra reviewed May 13, 2026

View reviewed changes

baszalmstra requested changes May 13, 2026

View reviewed changes

wolfv commented May 13, 2026

View reviewed changes

claude and others added 3 commits May 13, 2026 09:25

docs(publish): recommend pixi.toml for shared variant config files

2ea6595

Per @wolfv on #6109: variant-config files should live in [workspace.build-variants-files] in pixi.toml so all contributors and CI runs pick them up. `--variant-config` / `-m` is for one-off overrides only.

Merge branch 'main' into claude/add-build-variant-option-Ic7Ap

5a8c0c0

Merge branch 'main' into claude/add-build-variant-option-Ic7Ap

b71956f

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(publish): add `--variant` and `--variant-config` flags#6109

feat(publish): add `--variant` and `--variant-config` flags#6109
wolfv wants to merge 7 commits into
mainfrom
claude/add-build-variant-option-Ic7Ap

wolfv commented May 13, 2026

Uh oh!

baszalmstra commented May 13, 2026

Uh oh!

baszalmstra May 13, 2026

Uh oh!

baszalmstra May 13, 2026

Uh oh!

baszalmstra May 13, 2026

Uh oh!

baszalmstra May 13, 2026

Uh oh!

baszalmstra left a comment

Uh oh!

wolfv commented May 13, 2026

Uh oh!

wolfv May 13, 2026

Uh oh!

wolfv May 13, 2026

Uh oh!

wolfv May 13, 2026

Uh oh!

wolfv May 13, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants


		CLI overrides replace the matching key from the workspace `build-variants`; workspace keys that aren't named on the command line keep their full value list.

		### Providing additional variant config files

Conversation

wolfv commented May 13, 2026

Description

How Has This Been Tested?

AI Disclosure

Checklist:

Uh oh!

baszalmstra commented May 13, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

baszalmstra left a comment

Choose a reason for hiding this comment

Uh oh!

wolfv commented May 13, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants