MiniExcel: streaming XLSX and CSV for .NET without loading the workbook

What MiniExcel replaces, and for whom

The README frames the problem narrowly. Most .NET spreadsheet frameworks, it says, load all the data from a document into memory before you can work with it, and that is what causes memory consumption problems. MiniExcel's stated approach is different: rows are processed in a streaming manner, which the README describes as reducing consumption from potentially hundreds of megabytes to a few megabytes and preventing out-of-memory errors.

That framing tells you who this is for. It is for a background job that exports a hundred thousand rows from a database, for an upload endpoint that ingests a customer's spreadsheet without knowing its size, for a scheduled report where the process should not grow with the file. The README's own feature list puts memory first and mentions no dependency on Microsoft Office or COM+, with a DLL size under 500 KB. The audience is a .NET developer who wants rows in and rows out, not a document authoring tool.

How the streaming pipeline actually works

The README carries a diagram that lays out three paths side by side. Other frameworks go from a file into memory, then more memory, then workbooks and worksheets, and only then produce all rows at the same time. MiniExcel's path is unzipping the XLSX, parsing the OpenXML, converting to a model, and emitting rows with deferred execution, one at a time. The intermediate stages are labelled Stream rather than Memory.

The consequence is that the API returns a lazily evaluated sequence. The README recommends Stream.Query over the path-based overload "because of better efficiency", and the code sample shows a using block around File.OpenRead with stream.Query<UserAccount>(). The rows are produced as you enumerate them, which is also why LINQ composition works: the feature list mentions deferred execution and paging and complex queries over large datasets. The model conversion step is where a row becomes a POCO or stays dynamic. This is the mechanism that makes memory flat rather than proportional to row count, and it is also the mechanism that constrains what the library can do. A row-at-a-time reader has no natural place to hold a formula graph or a shared style table.

Installing MiniExcel and querying a file

The README points at NuGet for the library. Add the package to a project, then map a sheet to a class. The README's own example defines a UserAccount type with ID, Name, BoD, Age, VIP and Points properties and queries it:

public class UserAccount
{
    public Guid ID { get; set; }
    public string Name { get; set; }
    public DateTime BoD { get; set; }
    public int Age { get; set; }
    public bool VIP { get; set; }
    public decimal Points { get; set; }
}

var rows = MiniExcel.Query<UserAccount>(path);

There is also a stream form, which the README recommends: open the file, call Query on the stream inside a using block, and enumerate. Because the sequence is deferred, nothing is read until you iterate it, so wrap the enumeration in the same scope as the open stream.

The same work is available from a shell. The README documents a CLI distributed as a .NET tool:

dotnet tool install --global MiniExcel.Cli

After installation the command is miniexcel. The README gives a query invocation that takes an input path and a sheet name and writes JSON, and a convert invocation that moves between formats:

miniexcel query --input input.xlsx --sheet Sheet1
miniexcel convert --input input.csv --output output.xlsx
miniexcel convert --input input.xlsx --output output.csv --overwrite

Run miniexcel <command> --help for the full option list, per the README. NativeAOT executables for Windows, Linux and macOS are also published on GitHub Releases and do not require a .NET runtime. The README is explicit that this is command-line integration, not a native library FFI API, so a Python or Node process shells out and parses JSON rather than linking against a shared object. The README notes the tool accepts file paths and writes query results as JSON.

Where MiniExcel is the wrong tool

The feature list is short and literal: minimize memory, operate on rows in real time, support LINQ with deferred execution, avoid Office and COM+ dependencies, and provide a simple API for reading, writing and filling. Nothing in that list is about presentation. If your deliverable is a workbook with conditional formatting, charts, data validation dropdowns or pivot caches, the streaming model has nowhere to accumulate that state, and the README does not claim otherwise.

The second limitation is structural rather than missing. Deferred execution means the sequence is tied to the lifetime of the underlying stream. Enumerate a query after its stream is disposed and you have a bug that the type system will not catch. The README's own guidance to prefer Stream.Query is guidance about efficiency, and it quietly moves that lifetime responsibility onto the caller.

Third, the project is mid-transition. The README states that a version 2.0 preview exists with a new modular API, separate NuGet packages for Core and CSV, and asynchronous streaming through IAsyncEnumerable, shipped as prereleases. Anyone starting today on the 1.x line should assume the surface they write against is the one being reorganised, and should read V2-Upgrade-Notes.md before committing to a large call site.

MiniExcel against ClosedXML and ExcelDataReader

The difference between MiniExcel and ClosedXML is the shape of the object model. ClosedXML exposes a workbook you hold, with worksheets, ranges and styles you mutate; that model is what makes formatting and layout work possible, and it is also what makes memory scale with the document. MiniExcel does not give you a workbook to hold. It gives you a sequence of rows. If your code says worksheet.Cell("A1").Style, you are in the wrong library, and no amount of tuning changes that.

ExcelDataReader is the closer comparison, because it is also a reader. The README does not discuss it, so the honest statement is that MiniExcel is not reader-only: the same package covers query, export and template filling, and the CLI converts in both directions. A pipeline that only ever ingests spreadsheets and never produces one may not need the write side at all.

The third option worth naming is the new CLI itself. For a non-.NET process, the choice is between a native binding and shelling out to miniexcel query. The README is clear that the second is what is on offer, and that the output is JSON on stdout.

Maintenance, licensing and the cost of upgrading

The repository is not archived, and the last push was on 2026-09-23. The most recent release listed is 1.46.1 on 2026-08-22, following 1.46.0 the same day and 1.45.0 on 2026-06-26. Release notes live under docs/, and the README links a roadmap on the project's GitHub projects board. The project states it is part of the .NET Foundation and operates under that foundation's code of conduct, which matters if your organisation has procurement rules about governance.

The upgrade cost is the real budget line. The README describes version 2.0 as splitting Core and CSV into separate NuGet packages, adding IAsyncEnumerable support, and changing the API shape, with packages available as prereleases. That means an upgrade is not a version bump you can absorb silently; the upgrade notes file exists precisely because call sites move. If you adopt 1.x now, treat the 2.0 documentation as a forward-looking constraint on how you wrap the library: keep query and export behind a thin internal interface so the eventual migration touches one file.

Licensing is Apache-2.0. That is a permissive licence with an explicit patent grant and a notice requirement, but I am not a lawyer and this is not legal advice. The practical points to check are whether your distribution includes the NOTICE and licence text, and whether your own attribution obligations are satisfied when you ship the DLL inside a desktop or service product. The repository also carries a CITATION.cff and a Zenodo DOI, which is unusual for a library of this kind and worth knowing if you cite dependencies in internal documentation.

Editorial conclusion

Adopt MiniExcel when the job is moving rows between a spreadsheet and .NET types, especially on files large enough that a full workbook load would hurt. Do not adopt it as a general Excel manipulation library: the README describes reading, writing and template filling, and the V2 preview is where the API is being reshaped. Before committing, read README_V2.md and V2-Upgrade-Notes.md to see how much of your call sites would move, verify that your target framework is at least .NET 4.5, and check that Apache-2.0 terms fit your distribution model.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. mini-software/MiniExcel on GitHub
3. Project website
4. README
5. Releases