👁 Image
SpreadCheetah 1.27.0

SpreadCheetah

👁 Nuget
👁 GitHub Workflow Status (with event)
👁 Codecov

SpreadCheetah is a high-performance .NET library for generating spreadsheet (Microsoft Excel XLSX) files.

Features

• Performance (see benchmarks below)
• Low memory allocation (see benchmarks below)
• Async APIs
• No dependency to Microsoft Excel
• Supports .NET Standard 2.0 targets, such as .NET Framework
• Supports .NET 6 to .NET 10, with more optimizations enabled for later versions
• Trimmable and NativeAOT compatible

SpreadCheetah is designed to create spreadsheet files in a forward-only manner. That means worksheets from left to right, rows from top to bottom, and row cells from left to right. This allows for creating spreadsheet files in a streaming manner, while also keeping a low memory footprint.

Most basic spreadsheet functionality is supported, such as cells with different data types, styling, and formulas. More advanced functionality will be added in future releases. See the list of currently supported spreadsheet functionality in the wiki.

See Releases for release notes. This project adheres to Semantic Versioning.

How to install

SpreadCheetah is available as a package on nuget.org.

.NET CLI

dotnet add package SpreadCheetah

Package Manager

Install-Package SpreadCheetah

Basic usage

using (var spreadsheet = await Spreadsheet.CreateNewAsync(stream))
{
 // A spreadsheet must contain at least one worksheet.
 await spreadsheet.StartWorksheetAsync("Sheet 1");

 // Cells are inserted row by row.
 var row = new List<Cell>
 {
 new Cell("Answer to the ultimate question:"),
 new Cell(42)
 };

 // Rows are inserted from top to bottom.
 await spreadsheet.AddRowAsync(row);

 // Remember to call Finish before disposing.
 // This is important to properly finalize the XLSX file.
 await spreadsheet.FinishAsync();
}

See the Getting started guide in the wiki.

Other examples

• Writing to a file
• Styling basics
• Formula basics
• DateTime and formatting
• Data Validations
• Tables
• Adding an embedded image
• Performance tips

Using the Source Generator

Source Generators is a feature in the C# compiler. SpreadCheetah includes a source generator that makes it easier to create rows from objects. It is used in a similar way to the System.Text.Json source generator:

namespace MyNamespace;

// A plain old C# class which we want to add as a row in a worksheet.
// The source generator will pick the properties with public getters.
// The order of the properties will decide the order of the cells.
public class MyObject
{
 public string Question { get; set; }
 public int Answer { get; set; }
}

The source generator will be instructed to generate code by defining a partial class like this:

using SpreadCheetah.SourceGeneration;

namespace MyNamespace;

[WorksheetRow(typeof(MyObject))]
public partial class MyObjectRowContext : WorksheetRowContext;

During build, the type will be analyzed and an implementation of the context class will be created. We can then create a row from an object by calling AddAsRowAsync with the object and the context type as parameters:

await using var spreadsheet = await Spreadsheet.CreateNewAsync(stream);
await spreadsheet.StartWorksheetAsync("Sheet 1");

var myObj = new MyObject
{
 Question = "How many Rings of Power were there?",
 Answer = 20
};

await spreadsheet.AddAsRowAsync(myObj, MyObjectRowContext.Default.MyObject);

await spreadsheet.FinishAsync();

Here is a peek at part of the code that was generated for this example. As you can see, the generated code also takes advantage of using a pooled array to avoid memory allocations:

// <auto-generated />
private static async ValueTask AddAsRowInternalAsync(Spreadsheet spreadsheet, MyObject obj, CancellationToken token)
{
 var cells = ArrayPool<DataCell>.Shared.Rent(2);
 try
 {
 cells[0] = new DataCell(obj.Question);
 cells[1] = new DataCell(obj.Answer);
 await spreadsheet.AddRowAsync(cells.AsMemory(0, 2), token).ConfigureAwait(false);
 }
 finally
 {
 ArrayPool<DataCell>.Shared.Return(cells, true);
 }
}

The source generator can generate rows from classes, records, and structs. It can be used in all supported .NET versions, including .NET Framework, however the C# version must be 8.0 or greater. More features of the source generator can be seen in the wiki.

Benchmarks

The benchmark results here have been collected using BenchmarkDotNet with the following system configuration:

BenchmarkDotNet v0.15.8, Windows 11 (10.0.26200.7462/25H2/2025Update/HudsonValley2)
AMD Ryzen 7 9800X3D 4.70GHz, 1 CPU, 16 logical and 8 physical cores
 [Host] : .NET Framework 4.8.1 (4.8.9221.0), X64 RyuJIT VectorSize=256
 Job-CZIXIP : .NET 10.0.1 (10.0.1, 10.0.125.57005), X64 RyuJIT x86-64-v4
 Job-RRVADO : .NET 8.0.22 (8.0.22, 8.0.2225.52707), X64 RyuJIT x86-64-v4
 Job-LYYWPY : .NET Framework 4.8.1 (4.8.9221.0), X64 RyuJIT VectorSize=256

BuildConfiguration=Benchmark InvocationCount=1 UnrollFactor=1 

These libraries have been used in the comparison benchmarks: | Library | Version | |--------------------------------------------------------|--------:| | SpreadCheetah | 1.25.0 | | Open XML SDK | 3.3.0 | | ClosedXML | 0.105.0 | | EPPlusFree | 4.5.3.8 |

Disclaimer: The libraries have different feature sets compared to each other. SpreadCheetah can only create spreadsheets, while the other libraries used in this comparison can also open spreadsheets. SpreadCheetah is also a newer library and has been designed from the ground up to utilize many of the newer performance related features in .NET. The other libraries have longer history and need to take backwards compatibility into account. Keep this in mind when evaluating the results.

The code executed in the benchmark creates a worksheet of 100 000 rows and 10 columns filled with string values. Some of these libraries have multiple ways of achieving the same result, but to make this a fair comparison the idea is to use the most efficient approach for each library. The code is available in the Benchmark project.

<details open> <summary><h3>.NET 10</h3></summary>

| Library | Mean | Allocated | |----------------------------|-------------:|----------------:| | SpreadCheetah | 32.86 ms | 15.43 KB | | Open XML (SAX approach) | 342.90 ms | 363 887.36 KB | | EPPlusFree | 831.39 ms | 859 019.78 KB | | Open XML (DOM approach) | 922.37 ms | 751 348.83 KB | | ClosedXML | 1 486.15 ms | 1 458 468.00 KB | </details>

<details> <summary><h3>.NET 8</h3></summary>

| Library | Mean | Allocated | |----------------------------|-------------:|----------------:| | SpreadCheetah | 49.75 ms | 11.09 KB | | Open XML (SAX approach) | 457.21 ms | 398 258.16 KB | | EPPlusFree | 863.03 ms | 859 065.22 KB | | Open XML (DOM approach) | 1 064.36 ms | 751 343.52 KB | | ClosedXML | 1 705.63 ms | 1 505 382.48 KB | </details>

<details> <summary><h3>.NET Framework 4.8.1</h3></summary>

| Library | Mean | Allocated | |----------------------------|--------------:|----------------:| | SpreadCheetah | 220.14 ms | 488.33 KB | | Open XML (SAX approach) | 1 080.36 ms | 212 291.21 KB | | EPPlusFree | 1 388.29 ms | 1 305 697.32 KB | | Open XML (DOM approach) | 2 220.41 ms | 566 498.13 KB | | ClosedXML | 3 127.89 ms | 1 271 265.65 KB | </details>