/ClosedXML

ClosedXML is a .NET library for reading, manipulating and writing Excel 2007+ (.xlsx, .xlsm) files. It aims to provide an intuitive and user-friendly interface to dealing with the underlying OpenXML API.

Primary LanguageC#MIT LicenseMIT

ClosedXML

Release NuGet Badge .NET Framework .NET Standard Build status Open Source Helpers

💾 Download unstable CI build

ClosedXML is a .NET library for reading, manipulating and writing Excel 2007+ (.xlsx, .xlsm) files. It aims to provide an intuitive and user-friendly interface to dealing with the underlying OpenXML API.

For more information see the documentation or the wiki.

Release notes & migration guide

The public API is still not stable and it is a very good idea to read release notes and migration guide before each update.

Performance

Performance matters mostly for large files. For small files, few ms here or there doesn't matter. The presented data are from generally develop branch (currently 0.103-beta).

Runtime details ``` BenchmarkDotNet v0.13.8, Windows 11 (10.0.22621.2283/22H2/2022Update/SunValley2) AMD Ryzen 5 5500U with Radeon Graphics, 1 CPU, 12 logical and 6 physical cores .NET SDK 8.0.100-rc.1.23463.5 [Host] : .NET 7.0.11 (7.0.1123.42427), X64 RyuJIT AVX2 ```

Save

Description Rows Columns Time/Memory to insert data Save workbook Total time/memory
Mixed (text/number) workbook.
Gist		 250 000 15 1.619 sec / 117 MiB 6.343 sec 7.962 sec / 477 MiB
Text only workbook. Gist 1 000 000 10 6.302 sec / 402 MiB 17.134 sec 23.436 sec / 1880 MiB

Load

Description Rows Columns Time to load data Used memory
Load mixed workbook (10 text/5 number columns). 250 000 15 15.648 sec 236 MiB
Text only workbook. 1 000 000 10 49.046 sec 801 MiB

Load tests used files created during save test.

Frequent answers

  • If you get an exception Unable to find font font name or fallback font fallback font name. Install missing fonts or specify a different fallback font through ‘LoadOptions.DefaultGraphicEngine = new DefaultGraphicEngine(“Fallback font name”)’, see help page about missing fonts.
  • ClosedXML is not thread-safe. There is no guarantee that parallel operations will work. The underlying OpenXML library is also not thread-safe.
  • If you get an exception The type initializer for 'Gdip' threw an exception. on Linux, you have to upgrade to 0.97+.

Install ClosedXML via NuGet

If you want to include ClosedXML in your project, you can install it directly from NuGet

To install ClosedXML, run the following command in the Package Manager Console

PM> Install-Package ClosedXML

What can you do with this?

ClosedXML allows you to create Excel files without the Excel application. The typical example is creating Excel reports on a web server.

Example:

using (var workbook = new XLWorkbook())
{
    var worksheet = workbook.Worksheets.Add("Sample Sheet");
    worksheet.Cell("A1").Value = "Hello World!";
    worksheet.Cell("A2").FormulaA1 = "=MID(A1, 7, 5)";
    workbook.SaveAs("HelloWorld.xlsx");
}

Extensions

Be sure to check out our ClosedXML extension projects

Developer guidelines

The OpenXML specification is a large and complicated beast. In order for ClosedXML, the wrapper around OpenXML, to support all the features, we rely on community contributions. Before opening an issue to request a new feature, we'd like to urge you to try to implement it yourself and log a pull request.

Please read the full developer guidelines.

Credits