Guide · Open source
How to use BenchmarkDotNet: write, run and export .NET benchmarks
Updated · written with AI from the project's own documentation and checked against our catalogue data
BenchmarkDotNet is an open-source MIT-licensed C# library for measuring how fast .NET code runs. This guide is for .NET developers who want to compare implementations of a method or check whether a code change made something faster or slower. By the end you will know how to install the package, write a benchmark class, read the summary table and export results.
BenchmarkDotNetdotnet/BenchmarkDotNet · ★ 11.5k · MIT Install options & downloads Quick start
- 1Check the .NET SDK. Make sure the .NET SDK is installed, since BenchmarkDotNet is added to a project as a NuGet package.
- 2Add the NuGet package. Run dotnet add package BenchmarkDotNet in the project folder.
- 3Create a benchmark class. Write a public class with methods marked [Benchmark] that contain the code you want to measure.
- 4Add setup code. Put untimed preparation in a method marked [GlobalSetup] and use [Params] for input sizes.
- 5Mark a baseline. Use [Benchmark(Baseline = true)] on the method you want the others compared against.
- 6Run and read the summary. Run the benchmarks and compare Mean, Error, StdDev and Ratio in the summary table.
- 7Export the results. Choose an export format such as md, html, csv or json to share the measurements.
What you need before you start
BenchmarkDotNet is installed as a NuGet package into a .NET project, so you need the .NET SDK. The library supports Windows, Linux and macOS, and works with .NET 5+, .NET Framework 4.6.1+, .NET Core 2.0+, Mono and NativeAOT.
The README lists C#, F# and Visual Basic as supported languages, so it is not limited to C#.
Install BenchmarkDotNet with NuGet
Add the package to the project you want to benchmark using the dotnet command line.
dotnet add package BenchmarkDotNetWrite your first benchmark class
Mark the methods you want to measure with the [Benchmark] attribute. Any setup that should not be timed can go in a method marked [GlobalSetup]. Use [Params] to run the same benchmark with several input values.
The README example compares two hash functions, SHA256 and MD5, over byte arrays of two sizes. Each benchmark method returns a value, which helps prevent the compiler from removing the work being measured.
- [Benchmark] marks a method to measure.
- [GlobalSetup] runs setup code outside the measured work.
- [Params(1000, 10000)] runs each benchmark for every listed value.
[Benchmark]
public byte[] Sha256() => sha256.ComputeHash(data);
[Benchmark]
public byte[] Md5() => md5.ComputeHash(data);Compare methods against a baseline
To compare benchmarks with each other, mark one of them as the baseline. BenchmarkDotNet then compares every other benchmark with it. The README shows the baseline form as [Benchmark(Baseline = true)]. The baseline column in the results is the Ratio column.
[Benchmark(Baseline = true)]Run on several runtimes with jobs
To compare performance across environments, use jobs. Each [SimpleJob] attribute names a runtime, and BenchmarkDotNet runs the benchmarks on each one. The README examples use RuntimeMoniker values such as Net472, NetCoreApp30, NativeAot70 and Mono, and mention Net80 for .NET 8.0.
If you prefer not to use attributes, the README shows a fluent configuration using ManualConfig.CreateEmpty() and Job.Default.
[SimpleJob(RuntimeMoniker.Net80)]
[SimpleJob(RuntimeMoniker.Mono)]Read the summary table
After a run, BenchmarkDotNet prints a summary table. The main columns are Method, the parameter columns such as N, Mean (average time per call), Error and StdDev (spread of the measurements), and Ratio (comparison to the baseline). The report also lists the hardware and runtime environment, which matters when you share results.
The README notes that the library protects against common benchmarking mistakes and warns when a benchmark design or measurement looks wrong.
Export results
Results can be exported to several formats, including md, html, csv, xml and json, and plots can be produced as well. The README example uses the [RPlotExporter] attribute to add a plot to the output.
[RPlotExporter]What people use it for
- Comparing two implementations of a method, such as two hashing algorithms, to see which is faster.
- Checking whether a code change made a method faster or slower before merging it.
- Sharing reproducible benchmark results with a team by exporting them to md, csv or json.
- Comparing the same code across several .NET runtimes or Mono using jobs.
Frequently asked questions
Is BenchmarkDotNet free to use?
BenchmarkDotNet is released under the MIT licence, as shown in the README badge and linked LICENSE.md file. The source does not describe any paid tier.
What do I need to install BenchmarkDotNet?
The README lists the .NET SDK as the prerequisite. You install the library with dotnet add package BenchmarkDotNet in your project.
Does BenchmarkDotNet work with languages other than C#?
The README lists C#, F# and Visual Basic as supported languages. It does not list other languages.
Can I use BenchmarkDotNet to benchmark a whole web server or running application?
The source says the library targets console applications and that other types of applications are not supported for console-argument configuration. It is not described as a tool for benchmarking whole running applications or servers.
When is BenchmarkDotNet not worth it?
If you only need a quick stopwatch timing and not statistical rigor, the library adds setup and run time that may not be worth it. The README does not name specific alternatives.
Which operating systems and runtimes are supported?
The README lists Windows, Linux and macOS, and runtimes including .NET 5+, .NET Framework 4.6.1+, .NET Core 2.0+, Mono and NativeAOT.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
BenchmarkDotNet suits .NET developers who want reproducible, statistically sound comparisons of methods, runtimes or code changes, and it is adopted by large projects such as the .NET Runtime and Roslyn. If you only need a rough stopwatch timing, or you work outside C#, F# and Visual Basic, a lighter approach or a different tool may fit better.
Install options & downloads