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 cargo build, check, clippy, test, or llvm-cov against each combination with --no-default-features. This ensures your crate compiles and tests correctly regardless of which subset of features a user enables.

Installation

cargo install cargo-matrix

Usage

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

# Build every combination
cargo matrix build

# Lint every combination (pass extra flags after --)
cargo matrix clippy -- -- -D warnings

# Test every combination
cargo matrix test

# 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

Any flags after the subcommand -- separator are forwarded verbatim to cargo:

cargo matrix test -- --test-thread=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.