hyperfine 2.0

CHANGELOG.md

@@ -1,48 +1,49 @@
-# v2.0.0-alpha.2
+# v2.0.0
 
-## Changes
+See the breaking changes below when migrating from hyperfine 1.x.
-
-- Always run `--setup`, `--prepare`, `--conclude`, and `--cleanup` commands in a shell, even when benchmarked commands run directly. Improve error messages for these commands, see #990 (@sharkdp).
-- Require an explicit shell choice for commands containing unquoted, standalone shell operators such as `&&` or `>`: use `-S` to interpret shell syntax or `-N` to pass operators as literal arguments (@sharkdp).
-- Use a compact output layout on narrow terminals (@sharkdp).
-- Make plotting and analysis scripts runnable directly from GitHub with `uvx --from 'git+https://github.com/sharkdp/hyperfine' <script>` (@sharkdp).
-
-# v2.0.0-alpha.1
-
-This is the first alpha release of hyperfine 2.0. Command-line options and export formats may change before the stable release. See the breaking changes below when migrating from hyperfine 1.x.
 
 ## Features
 
-- Add support for alternative performance metrics (peak memory usage, CPU cycles, instructions, cache misses, branch misses, ...). By default, hyperfine will now display wall-clock time and peak memory usage (wall-clock time only on Windows),
+- Add support for alternative performance metrics (peak memory usage, instructions, CPU cycles, cache misses, branch misses, ...). By default, hyperfine will now display wall-clock time and peak memory usage, but users can use the [new `--metrics` option](README.md#choosing-metrics-and-units) to select different performance metrics. The terminal output now shows an overview of all selected performance metrics, including relative changes.
-  but users can use the new `--metrics` option to select different performance metrics.
+- Add `--env` to set environment variables even without an intermediate shell (which is the new default behavior, see below). For example:
-- The terminal output now shows an overview of all selected performance metrics, including relative changes.
+
-- Python plotting and analysis scripts support the new JSON format and can select performance metrics with `--metric`, see #981 and #984 (@sharkdp).
+  ```sh
+  # Parameterized benchmark, comparing different thread counts:
+  hyperfine -P threads 1 8 --env 'OMP_NUM_THREADS={threads}' 'my_command'
+  ```
+
+- The plotting and analysis scripts now support different metrics as well, see #981 and #984 (@sharkdp).
 
 ## Breaking changes
 
-- Benchmarked commands are now executed directly by default, without an intermediate shell (`--shell=none`). Use `-S` (an alias for `--shell=default`) to restore the previous behavior (`sh` on Unix, `cmd.exe` on Windows), or select a shell with `--shell <SHELL>`.
+- Benchmarked commands are now executed directly by default, without an intermediate shell (`--shell=none`). Use `-S` (an alias for `--shell=default`) to restore the previous behavior (`sh` on Unix, `cmd.exe` on Windows), or select a shell with `--shell <SHELL>`. See [the rationale for this change](https://github.com/sharkdp/hyperfine/issues/787#issuecomment-6038898252).
-- The JSON format for `--export-json` has changed (schema version 2). The new format now includes metadata, per-run measurements, and statistical summaries for all measured quantities, see #790 (@sharkdp). Code that reads those exported JSON files must be updated. For example, `results[i].mean` is now `results[i].summary.time_wall_clock.mean`, and `results[i].times` is replaced by `results[i].measurements[j].time_wall_clock.value`. The new structure looks like this:
+- Always run `--setup`, `--prepare`, `--conclude`, and `--cleanup` commands in a shell, even when using `--shell=none` (the new default behavior), see #990 (@sharkdp).
+- The JSON format for `--export-json` has changed (schema version 2). The [new format](README.md#json) now includes metadata, per-run measurements, and statistical summaries for all measured quantities, see #790 (@sharkdp). Code that reads those exported JSON files must be updated. For example, `results[i].mean` is now `results[i].summary.time_wall_clock.mean`, and `results[i].times` is replaced by `results[i].measurements[j].time_wall_clock.value`. The new structure looks like this:
 
   ```python
   {
       "schema_version": 2,
       "primary_metric": "time_wall_clock",
       "metadata": {
-          "hyperfine_version": "2.0.0-alpha.1",
+          "hyperfine_version": "2.0.0",
           "start_time": "2026-10-06T12:00:00Z",
           "platform": {"os": "Linux", "architecture": "x86_64"}
       },
       "results": [
           {
               "command": "sleep 1",  # Actual command after parameter substitution
-              "name": "wait 1s",  # Optional custom name, separate from the command
+              "name": "wait 1s",  # Optional custom or automatically generated name
               "parameters": {"duration": {"value": "1"}},  # Values are now objects
+              "environment": {"OMP_NUM_THREADS": "8"},  # Only present with --env overrides
               "measurements": [  # One entry per run, excluding warmups
                   {
                       "time_wall_clock": {"value": 1.0, "unit": "second"},
+                      "time_cpu": {"value": 0.0, "unit": "second"},
                       "time_user": {"value": 0.0, "unit": "second"},
                       "time_system": {"value": 0.0, "unit": "second"},
                       "memory_peak_resident": {"value": 1048576.0, "unit": "byte"},
+                      "cpu_cycles": {"value": 5000000},  # Hardware counters, when available
+                      "instructions": {"value": 10000000},
                       "exit_code": 0
                   },
                   ...  # Further runs omitted
@@ -64,11 +65,11 @@ This is the first alpha release of hyperfine 2.0. Command-line options and expor
   }
   ```
 
-  Times are always exported in seconds and memory in bytes.
+  Times are always exported in seconds and memory in bytes. Hardware counters and their summaries have no `unit` field. Unavailable memory measurements and hardware counters are omitted; other available counters may also be included. `stddev` is `null` for a single run.
 - `--time-unit`/`-u` has been removed. Units can now be selected using the `--metrics METRIC[:UNIT],…` option, e.g. `--metrics time_wall_clock:ms,memory_peak_resident:MiB`.
 - `--sort` has been removed. It complicated hyperfine significantly and doesn't make too much sense with the new output format.
-- `--reference` and `--reference-name` have been removed (for now). The first command is always considered as the reference command.
+- `--reference` and `--reference-name` have been removed (for now). The first command is always considered as the reference command. Invocations using `--reference` now show migration guidance to put the reference command first.
-- The format of Markdown, AsciiDoc, org-mode and CSV exports has also been changed. These formats contain only the primary metric (the first metric selected by `--metrics`). CSV now includes columns with the name and the unit of the primary metric.
+- The format of [Markdown](README.md#markdown), AsciiDoc and org-mode, and [CSV](README.md#csv) exports has also been changed. Markdown, AsciiDoc, and org-mode contain only the primary metric (the first metric selected by `--metrics`). CSV exports all selected metrics side by side.
 
 # v1.21.0
 

CITATION.cff

@@ -13,5 +13,5 @@ authors:
 repository-code: 'https://github.com/sharkdp/hyperfine'
 abstract: A command-line benchmarking tool.
 license: MIT
-version: 2.0.0-alpha.2
+version: 2.0.0
 date-released: '2026-10-07'

Cargo.lock

@@ -377,7 +377,7 @@ checksum = "15cdd26707701c53297e2fa6afb323d55fbc1d0810c3aec078ae3ef0424c3c15"
 
 [[package]]
 name = "hyperfine"
-version = "2.0.0-alpha.2"
+version = "2.0.0"
 dependencies = [
  "anyhow",
  "approx",

Cargo.toml

@@ -7,7 +7,7 @@ license = "MIT OR Apache-2.0"
 name = "hyperfine"
 readme = "README.md"
 repository = "https://github.com/sharkdp/hyperfine"
-version = "2.0.0-alpha.2"
+version = "2.0.0"
 edition = "2018"
 build = "build.rs"
 rust-version = "1.97.0"

README.md

@@ -331,8 +331,8 @@ apt install hyperfine
 
 Alternatively, for the latest version, you can download the appropriate `.deb` package from the [Release page](https://github.com/sharkdp/hyperfine/releases) and install it via `dpkg`:
 ```
-wget https://github.com/sharkdp/hyperfine/releases/download/v1.21.0/hyperfine_1.21.0_amd64.deb
+wget https://github.com/sharkdp/hyperfine/releases/download/v2.0.0/hyperfine_2.0.0_amd64.deb
-sudo dpkg -i hyperfine_1.21.0_amd64.deb
+sudo dpkg -i hyperfine_2.0.0_amd64.deb
 ```
 
 ### On Fedora

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "hyperfine-scripts"
-version = "0.1.0"
+version = "2.0.0"
 description = "Plot and analyze hyperfine JSON benchmark results"
 requires-python = ">=3.10"
 license-files = ["LICENSE-APACHE", "LICENSE-MIT"]