EPPlus 8: Excel spreadsheets in .NET with a mandatory startup declaration

EPPlus and OOXML: C# code that reads and writes xlsx on netcore, netframework and netstandard

EPPlus is a C# library for reading and writing Excel spreadsheets in .NET code. The project's GitHub topics name netcore, netframework and netstandard as supported targets, so the same package version serves .NET Framework legacy applications, .NET Core services, and class libraries targeting netstandard. The description is direct: "Excel spreadsheets for .NET."

OOXML is listed among the project topics, and xlsx is an OOXML container. EPPlus operates on this format directly rather than automating a running Excel installation. Application code opens or creates an xlsx file, modifies its contents through the library API, and writes it back within the .NET runtime without involving an external process.

The ExcelPackage class is the entry point shown in the README. It takes a FileInfo pointing to the target file:

using(var package = new ExcelPackage(new FileInfo("MyWorkbook.xlsx")))
{

}

Work happens inside the using block. Passing an existing file path opens the file; a path to a file that does not yet exist creates it on write. Distribution is through NuGet under the package name EPPlus: the README links to https://www.nuget.org/packages/EPPlus/ as the distribution page. A SECURITY.md file at the repository root handles vulnerability reporting.

The startup declaration that EPPlus 8 requires before ExcelPackage opens any file

Version 8 of EPPlus requires a startup declaration before any file operation. The README is explicit on this: three methods on a static property handle the three deployment contexts, and without a call to one of them the library will not open or create a workbook.

ExcelPackage.License.SetCommercial("<Your License Key here>");
ExcelPackage.License.SetNonCommercialPersonal("<Your Name>");
ExcelPackage.License.SetNonCommercialOrganization("<Your Noncommercial Organization>");

Commercial deployments call the first method with a key string. Personal noncommercial work calls the second with a name. An organisation operating under Polyform Noncommercial calls the third with an organisation name string. The README places these calls before any ExcelPackage constructor in all its code examples, signalling that they belong in application startup rather than inside request handlers or background tasks.

The two noncommercial methods differ in the name string they record inside the output file. SetNonCommercialPersonal takes an individual's name; SetNonCommercialOrganization takes an organisation name. Both produce the same noncommercial context for subsequent ExcelPackage use. A declaration that runs after ExcelPackage is already instantiated, or one that passes an incorrect key format, produces an error at that point rather than at a later worksheet access.

Delivering the startup configuration through JSON, XML, and an environment variable

The startup value can reach EPPlus through three external configuration paths, and the choice among them is a deployment question rather than a technical one.

For projects using appSettings.json, the nested key structure uses colons between segments:

{
    "EPPlus": {
        "ExcelPackage": {
            "License": "Commercial:<Your License Key here>" 
            }
        }
}

The noncommercial equivalent uses the same nested structure, replacing the commercial value string with NonCommercialPersonal:<Your Name> or NonCommercialOrganization:<Your organizations name>.

For app/web.config, the equivalent key uses a dot before the final segment rather than a colon, making the separator inconsistent with the JSON path. That difference is easy to miss when copying settings between the two formats.

An environment variable named EPPlusLicense accepts the same value strings. The README shows the Windows SETX command:

> SETX EPPlusLicense "Commercial:<Your License Key>"

Container runtimes, CI pipelines with secret injection, and managed hosting that exposes variable configuration can all deliver the startup setting through this path without modifying application code. For a containerised deployment where application source is treated as read-only across environments, this path avoids any code modification.

What noncommercial mode writes into the xlsx package and overwrites in its metadata

Choosing a noncommercial deployment context changes what EPPlus writes into every xlsx file it produces in two ways that go beyond normal spreadsheet content.

EPPlus adds a file within the package itself. An xlsx archive holds multiple documents alongside the worksheet data, shared strings and styles. EPPlus appends its own file to record the deployment context, and any inspection of the package structure will surface this entry alongside the standard worksheet files.

In parallel, the Comment and Tag fields in the document-level metadata receive a context string. Those two properties appear in xlsx package metadata alongside the author, title and subject. A downstream pipeline that reads Comment to track document origin, or reads Tag for routing and classification, will receive the EPPlus-written content rather than any value the application intended to place there. No documented configuration path disables this behaviour while remaining in the noncommercial context; EPPlus reserves those fields as part of the noncommercial deployment mode, not as an optional annotation.

For a tool that generates workbooks for direct human use, the effect is invisible in normal operation. For any pipeline that parses Comment or Tag from files EPPlus produces, the replacement is silent and will only surface during explicit testing against noncommercial output.

Polyform Noncommercial 1.0.0, commercial deployments, and the February 2025 key boundary

EPPlus 8 uses Polyform Noncommercial 1.0.0 for noncommercial deployment contexts and requires a paid commercial arrangement for business deployments. The boundary definition lives in the FAQ at epplussoftware.com; the README does not reproduce it.

Commercial deployments include support. Noncommercial use carries no support entitlement. CONTRIBUTING.md at the repository root and the GitHub issue tracker are the documented routes for feedback and bug reports from noncommercial users.

One sentence in the README rewards careful reading. Keys for commercial use are available "under the section 'My Licenses' on our website and on EPPlus license documents created after February 2025." A document issued before that date does not include the key. An organisation that purchased EPPlus commercially before February 2025 holds a document that does not carry what the startup call requires. The only recovery path the README names is the website account section under My Licenses. No support ticket route, reissue form, or offline alternative is described anywhere in the README.

This February 2025 boundary appears in a single sentence and is easy to overlook when scanning for setup steps. A commercial migration from a pre-v8 version should confirm key availability on the website before writing any startup code.

Version 8.7.1 stable and v9.0.0-preview on the same day, with breaking changes linked externally

Version 8.7.1 and v9.0.0-preview both landed on 2026-09-22: the stable build at 11:31 UTC, the preview at 13:48 UTC. The default branch is develop8. A v9 preview and a v8 patch shipping on the same day point to parallel maintenance of both lines, but the README is written for EPPlus 8 and gives no guidance on the v9 lifecycle or how the startup configuration will work at that version.

Two URLs in the README link to pages not reproduced in the repository: breaking changes at https://github.com/EPPlusSoftware/EPPlus/wiki/Breaking-Changes-in-EPPlus-8 and new features at https://epplussoftware.com/en/Developers/EPPlus8. For a team upgrading from an earlier version, the breaking changes page is the first document to examine before changing the dependency version number. For a team deciding between v8 and v9 for a new project, the preview label marks the v9 API as subject to change before a stable cut.

There is no mention in the README of whether v9 will carry the same Polyform Noncommercial arrangement or whether the startup configuration mechanism will change. The repository last received a commit on 2026-10-06.

Where EPPlus does not apply: format gaps and the cost of the startup constraint

EPPlus names xlsx and OOXML as its format in the project description and GitHub topics. The older binary Excel format, which predates the OOXML era, appears nowhere in the description, topics or README. Projects that receive binary-format Excel files from external systems, or that must produce that format for legacy consumers, need a separate library or a conversion step that EPPlus cannot provide.

PDF, HTML and image rendering are absent from the README. A reporting pipeline that must deliver printable output from spreadsheet data requires a second tool for that rendering step.

The startup sequencing constraint adds friction for containerised and serverless deployments. If EPPlusLicense is unavailable when the process starts, or a code path instantiates ExcelPackage before the startup call has run, the error appears immediately at that point. No lazy initialisation is documented and no deferred check exists. A startup integration test that calls the method block from the section above, then opens a test ExcelPackage against a known file, confirms the configuration before any deployment. An xlsx consumer that reads Comment or Tag from files produced in the noncommercial context also needs to account for the EPPlus-written content in those fields rather than any application value.

Editorial conclusion

EPPlus fits .NET teams that generate or process Excel files from application code and are comfortable with a NuGet dependency that enforces a startup declaration. Commercial deployments require a paid key from epplussoftware.com, and any existing commercial customer holding a document predating February 2025 must retrieve the key from the website before the startup call will accept it. Noncommercial users need to confirm that no part of their xlsx consumer reads the Comment or Tag metadata fields, because EPPlus writes its own context data into both without any documented override. The first integration step is to verify the startup call runs before any ExcelPackage constructor in the startup sequence and that no error is thrown before the first worksheet access.

Frequently asked questions

Official sources

1. EPPlusSoftware/EPPlus on GitHub
2. Issues
3. Project website
4. README
5. Releases