# cargo-matrix
## Current Releases
### cargo-matrix
[](https://crates.io/crates/cargo-matrix)
[](https://crates.io/crates/cargo-matrix)
[](https://crates.io/crates/cargo-matrix)
### CI/CD
[](https://github.com/rustyhorde/cargo-matrix/actions)
`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
```sh
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.
```sh
# 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:
```sh
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.
```toml
[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
| `name` | `string` | Channel identifier. `"default"` is the fallback for all other channels. |
| `seed` | `[string]` | If set, use only these features as the powerset input instead of the package's full feature list. |
| `always_deny` | `[string]` | Features excluded from every generated combination. |
| `always_include` | `[string]` | Features added to every generated combination. |
| `skip` | `[[string]]` | Exact feature sets to drop from the matrix. |
| `mutually_exclusive` | `[[string]]` | Feature groups where at most one member may appear in any combination. |
| `include_hidden` | `bool` | Include `__`-prefixed features in the powerset. Defaults to `false`. |
| `include_all_optional` | `bool` | Add every optional dependency as a feature. Defaults to `false`. |
| `include_optional` | `[string]` | Add specific optional dependencies as features. |
## License
Licensed under either of [Apache License, Version 2.0](LICENSE-APACHE) or
[MIT license](LICENSE-MIT) at your option.