Skip to content

helicoprion

helicoprion is a benchmarking tool for sched_ext. It runs the same workloads with each scheduler and puts the results side by side in an HTML report. Start by comparing an installed scheduler with the kernel default.

The examples on this page target helicoprion 0.5.0. Install the helicoprion release on crates.io with Cargo:

Terminal window
cargo install --locked helicoprion
helicoprion --version

If the command is not found, check that Cargo’s binary directory (~/.cargo/bin by default) is on your PATH. To build from source, check out one of the helicoprion release tags and run cargo build --release --locked. The binary is target/release/helicoprion.

matrix switches the active scheduler during the test. Run it when you can leave the machine idle.

Follow the sched_ext installation guide if you still need scxcli, scx.service or a scheduler to test. Then check your kernel and switching tools. To see which scheduler is running and which alternatives the catalog recommends, run:

Terminal window
helicoprion info
scxcli list recommended

If none of the recommended schedulers is installed, use scxcli list to find an installed alternative and pick it by name. If you don’t have the switching tools yet, you can still measure the running scheduler.

matrix also needs compatible JSON from both scxcli get --json and scxcli list --json. Both must report top-level "version": 2. If either command is unavailable or reports a different schema, use run without switching schedulers.

Close builds, games and other background jobs. Keep the same power settings throughout the test. This command compares the installed recommendations with the kernel default using the quick suite:

Terminal window
sudo -- "$(command -v helicoprion)" matrix --recommended --simple -o comparison/

The explicit path lets sudo find a Cargo installation. Use a new or empty output directory. Before starting, helicoprion prints a time estimate. It runs five rounds by default and reverses the scheduler order each round, so the same scheduler does not always go first as the machine warms up.

Before switching, matrix checks whether it can reconstruct the starting state. It can refuse to start when there are active service overrides, runtime-only enablement, or a mismatch between the service and the running scheduler. See sched_ext troubleshooting before retrying.

On completion, error, or the first Ctrl+C, helicoprion attempts and checks restoration. To stop early, press Ctrl+C once and wait. A second Ctrl+C exits without restoring. If restoration fails, use the recovery commands printed at the start, then check scxcli get and helicoprion info.

Open comparison/report.html in your browser and start with In short. If you care about responsiveness under load, look at the slowest wake-ups in the Busy system result. Completing more round trips per second does not necessarily mean shorter delays. No clear difference means the results did not meet the report’s criteria for a clear change, not that the schedulers performed identically. Expand Full report for the metrics and check Conditions for changes in temperature, CPU frequency or load.

To test just one alternative against the kernel default, use --sched instead of --recommended. The first entry is the baseline. Replace scx_lavd with an installed scheduler from scxcli list if needed:

Terminal window
sudo -- "$(command -v helicoprion)" matrix --sched default --sched scx_lavd \
--simple -o default-vs-lavd/

Open default-vs-lavd/report.html for this comparison. Add another --sched entry to include another scheduler in the same rounds.

  • quick (default) measures thread hand-offs on an idle and a busy system.
  • periodic measures timer wake-ups and missed deadlines, with and without background CPU load. Start here for a workload closer to regular frame or audio deadlines.
  • bursts measures how quickly groups of workers start and finish when woken together.
  • cgroups checks how the scheduler divides CPU time between groups with different weights and thread counts. It needs root and cgroup v2 with the cpu controller available.
  • all runs every suite above, including cgroups.

Pass --suite periodic, for example, to either run or matrix. See what each workload measures before choosing which results to compare.

You don’t need sched_ext tools or sudo to measure the current scheduler with the default workload:

Terminal window
helicoprion info
helicoprion run -o current.json

info shows the kernel, CPU and active scheduler. run writes a JSON result without switching schedulers. The kernel’s fair scheduler name (CFS or EEVDF) is inferred from the kernel version. BORE and attached sched_ext schedulers are detected separately. For comparing schedulers, prefer matrix: separate runs can be affected by changes in temperature or background activity.

helicoprion checks the scheduler before and after each run and leaves invalid runs out of the comparison. If the kernel does not expose enable_seq, it cannot detect a restart of the same sched_ext scheduler between those checks.

The report counts clear changes per workload rather than ranking schedulers by a single score. A better result in one workload is a reason to try the scheduler with your own applications, not a guarantee that it will be better for everything.

To compare saved JSON files without switching schedulers, pass them to compare. This example uses the files from the default-vs-lavd/ comparison above. The first file is the baseline unless you set --baseline. Add --svg-dir charts/ to save the charts separately:

Terminal window
helicoprion compare default-vs-lavd/00-default.json default-vs-lavd/01-scx_lavd.json \
-o report.html --svg-dir charts/

To see whether two sessions agree, run the same matrix command again with a new output directory. For example, repeat the first comparison with -o comparison-repeat/, then pass both directories to sessions:

Terminal window
helicoprion sessions comparison/ comparison-repeat/ -o sessions.html

Two sessions show whether those runs agree. Use at least five comparable sessions to judge how often a result repeats; that is a practical minimum, not a statistical guarantee.

sessions reports setup differences that prevent comparison and fields it could not check. When the setups match, it shows the results side by side without pooling the runs. To see how much the benchmark varies without a scheduler change, run a separate comparison with --sched default --sched default. This A/A check uses six rounds by default. If you set --rounds yourself, use an even number.

© 2026 Seafoam LabsShelly Chel