cargo-matrix

Current Releases

cargo-matrix

CI/CD

cargo-matrix is a Cargo subcommand that runs feature matrices against cargo commands. For each crate in your workspace it discovers all features, generates every valid combination (the powerset), and runs the cargo command you give it (e.g. build, check, clippy, test, nextest run, llvm-cov) against each combination with --no-default-features. Any cargo command that accepts -p/--package, -F/--features, and --no-default-features works. This ensures your crate compiles and tests correctly regardless of which subset of features a user enables.

Installation

cargo install cargo-matrix

Usage

cargo matrix runs the cargo command you give it once per feature combination, injecting -p <package>, --no-default-features, and -F <features> for each one. Any cargo command that accepts those flags works — there is no fixed list of supported subcommands.

# Check every feature combination across the entire workspace
cargo matrix check

# Build every combination
cargo matrix build

# Test every combination
cargo matrix test

# Multi-token commands work too — just type the full command
cargo matrix nextest run
cargo matrix llvm-cov nextest

# Measure coverage across every combination
cargo matrix llvm-cov

# Dry run — print what would be run without executing anything
cargo matrix --dry-run check

# Run against a specific package only
cargo matrix --package my-crate check

# Select a named channel (see Configuration below)
cargo matrix --channel nightly clippy

# Point at a workspace that isn't in the current directory
cargo matrix --manifest-path path/to/Cargo.toml check

# Split the workspace into chunks for parallel CI jobs (e.g. three jobs, run the second)
cargo matrix --num-chunks 3 --chunk 2 test

The matrix flags (--channel, --dry-run, --manifest-path, --package, --num-chunks, --chunk) must come before the command. Everything from the command onward is passed to cargo.

Anything after a -- separator is forwarded verbatim to the underlying command, after the injected matrix flags:

cargo matrix test -- --test-threads=1
cargo matrix clippy -- -D warnings -A clippy::pedantic

Configuration

Configure each crate via [package.metadata.cargo-matrix] in its Cargo.toml. All fields are optional — without any configuration cargo-matrix uses the full feature powerset.

Configuration is grouped into named channels, which lets you maintain different filter sets for different toolchains or purposes (e.g. default, nightly, llvm-cov). Select a channel at runtime with --channel <name>. When a named channel does not define a field, the value falls back to the "default" channel.

[package]
name = "my-crate"
# ...

[features]
foo = []
bar = []
baz = ["dep:serde"]
unstable = []
__internal = []

[dependencies]
serde = { version = "1", optional = true }

[package.metadata.cargo-matrix]

# ── default channel ────────────────────────────────────────────────────────────
[[package.metadata.cargo-matrix.channel]]
name = "default"

# Never include these features in any generated combination.
always_deny = ["unstable"]

# Always add these features to every combination.
always_include = []

# Drop these exact combinations from the matrix.
skip = [["foo", "baz"]]

# Feature groups — any combination containing two or more features from the
# same group is excluded. Useful for mutually exclusive backends or runtimes.
mutually_exclusive = [["foo", "bar"]]

# Override the powerset seed entirely. When set, only these features are
# combined; the package's full feature list is ignored.
# seed = ["foo", "bar"]

# Include features whose names start with "__" (hidden/internal features).
# Defaults to false.
include_hidden = false

# Automatically include every optional dependency as a feature.
include_all_optional = false

# Include specific optional dependencies as features, independent of
# include_all_optional.
include_optional = ["serde"]

# ── nightly channel ────────────────────────────────────────────────────────────
[[package.metadata.cargo-matrix.channel]]
name = "nightly"

# Override just what differs from the default channel.
always_deny = []
always_include = ["unstable"]
include_hidden = true

Channel field reference

License

Licensed under either of Apache License, Version 2.0 or MIT license at your option.