OpenXLSX for C++ Excel File Handling

OpenXLSX Targets Native C++ Spreadsheet Automation

OpenXLSX addresses the need to manipulate Microsoft Excel .xlsx files directly from C++ code. Its documented scope covers reading, writing, creating and modifying workbooks. That makes it relevant to report generators, data import tools, command-line utilities and desktop applications that exchange spreadsheet files with Excel users. The project is associated with C++17 and is organized around a native library rather than a server service or command-line application.

The repository includes an OpenXLSX/ library directory, an Examples/ directory containing Demo1.cpp through Demo10.cpp, a Tests/ directory and a Benchmarks/ directory. It also contains CMakeLists.txt, Makefile.GNU and vcpkg.json. Based on that layout, the project supports several integration paths: source integration through CMake, a separately built library, a GNU Make workflow and package management through vcpkg.

OpenXLSX does not attempt to reproduce Excel's interface. It operates on the .xlsx workbook format through C++ APIs. That distinction becomes important when an application depends on advanced workbook behavior. The README's to-do list includes tables and filters, true hyperlink support, XML comments and rich text elements in cell strings. Those pending features define the current scope more clearly than the broad project description alone.

OpenXLSX Models Workbooks, Worksheets and Styles

The documented API includes XLDocument, XLWorksheet, XLCellReference and XLStyles. These names indicate an object-oriented design centered on workbook documents, worksheets, cell positions and style records. The repository also contains archive and XML components, including Zippy.hpp and LibZip.hpp. That separation places workbook-level operations above lower-level archive access and XML processing.

The release notes for v0.5.1 describe how document creation works. XLDocument::create loads the document into memory, closes the file handle and initializes the archive from memory. The same change addresses deletion of a temporary workbook template file. Another update changes loadArchiveData from text mode to binary mode. These details indicate that .xlsx archive handling is part of the implementation rather than an incidental file operation.

Worksheet structure is controlled explicitly. The constructor for XLWorksheet removes the worksheet dimension element, and setDimension functions can establish it afterward. The documented overloads accept XLCellReference values, two strings or one dimension string. An overload can also calculate the last cell. This is relevant to compatibility with spreadsheet software because the worksheet dimension records the used range. The README does not claim that OpenXLSX automatically preserves every worksheet dimension after arbitrary modification.

The README labels its reference guide as still to be written. Exact method signatures and ownership rules should therefore be checked in the OpenXLSX headers and examples on Codeberg before integration.

OpenXLSX CMake and Dependency Decisions

CMake is the principal integration path documented by the repository. The release notes for v0.5.1 state that the configuration was changed to locate locally installed library versions and determine the required library type. When enabled, the build can also download missing dependencies from upstream. This can reduce manual installation work, although projects that restrict network access during builds will need all required dependencies available locally.

Dependency mode affects packaging. The monolithic library can be requested with the OPENXLSX_MONOLITHIC_LIBRARY CMake option. The README states that this mode requires static dependencies and works with miniz. It does not produce the same bundled library with libzip because the libzip sub-dependencies are not linked into the resulting monolithic file. A project that wants one packaged artifact therefore needs to account for this boundary.

The repository also contains Makefile.GNU, but its to-do list says that BUILD_SHARED_LIBS support still needs to be implemented. It also needs logic to detect unavailable dependencies and report an error. This makes Makefile.GNU a secondary path unless a project already depends on that workflow. The vcpkg manifest offers another packaging route, and the April 2026 changes describe improved vcpkg compatibility. The README does not publish the dependency versions in vcpkg.json, so they must be checked in that file rather than inferred.

Building OpenXLSX and Running a First Example

The README organizes installation into platform preparation, building the library, integration into a CMake project and compilation against an installed OpenXLSX library. It names cmake and git as prerequisites on Debian-based Linux distributions. It also has Windows instructions for MSYS Makefiles, while the May 2024 update says the library has been tested on Windows, macOS and Linux.

The README does not show the complete copy, configure and install command sequence in its build passages. It would be inaccurate to invent flags, directories or compiler arguments. The documented CMake option can nevertheless be recorded exactly as published:

-DOPENXLSX_MONOLITHIC_LIBRARY=ON

This option requests monolithic mode, requires static dependencies and works with miniz according to the README. A reader should place it after the configure command published in the current Codeberg build instructions. It is not a complete build command by itself.

For a first real use, open Examples/CMakeLists.txt and select the numbered file under Examples/ that demonstrates the required operation. Start with an example close to the intended workflow, then configure the example using the commands in the current README. The expected result is a linked C++ program that performs the workbook operation demonstrated by that file. The repository does not specify one universal output filename because each Demo file represents a different use case.

The README also includes sections for compiling and linking a program with g++ and CMake. Exact compiler and linker arguments should be copied from the current Codeberg instructions rather than reconstructed. This matters because OpenXLSX links against archive and XML dependencies that must match the selected build mode.

Unicode Paths and Worksheet Dimensions in OpenXLSX

OpenXLSX includes a to-do item for predictable Unicode path handling in several areas. The June 2026 changes partially address this problem. XLDocument::create now uses nowide functions for temporary file creation when creating a Unicode path. An additional update changes pathExists to use nowide::stat when nowide is enabled, affecting XLDocument::create and XLDocument::saveAs checks. A new fileSize wrapper also uses stat compatibility.

These changes improve filename handling for paths containing Unicode characters, but they do not establish that every operating system and toolchain combination behaves identically. Windows, macOS and Linux use different path and filesystem conventions. The README states broad platform support and mentions Windows testing with MSYS Makefiles, yet it does not publish a detailed matrix of compiler versions or Unicode path cases.

Worksheet dimension handling is another practical concern. Because the constructor deletes the dimension and setDimension restores it, applications that calculate used ranges must invoke the appropriate overload after changing a sheet. The auto-calculation option can derive the last cell, but callers should verify that the recorded top-left and bottom-right references match their intended reporting range. Failure to update the dimension may cause a spreadsheet application to interpret the used range differently from what the C++ code intended.

OpenXLSX also changed archive loading to binary mode. That is relevant when opening or saving .xlsx files through the archive layer, but the README does not provide a benchmark result or performance claim for the change.

OpenXLSX Feature Gaps Limit Some Workbook Scenarios

The clearest limitation is the pending feature list. Tables and filters are not implemented. True hyperlink support is also marked as a to-do item. XLWorksheet still needs support for XML comments, and rich text elements in cell strings are listed as another pending feature. XLStyles does not support all predefined number formats that have meaningful named constants.

These omissions make OpenXLSX a poor fit for workflows that depend on advanced Excel features, even when basic cell values and styles are sufficient. A report generator that emits ordinary strings and numbers may fit the documented scope. A document editor intended to round-trip comments, rich text, filtered tables or genuine hyperlinks requires features the README says are absent.

The project also has a monolithic packaging constraint. OPENXLSX_MONOLITHIC_LIBRARY works with miniz, but libzip sub-dependencies are not included in the resulting bundled library. A team whose packaging policy requires a single dependency-free binary cannot assume that every archive backend supports that output.

OpenXLSX may also be the wrong tool for developers who want a complete reference guide. The README labels that guide as to be written. This does not prevent use, but it means the headers, examples and current Codeberg repository carry more of the documentation burden.

OpenXLSX Versus a Higher-Level Spreadsheet API

OpenXLSX is best compared with higher-level spreadsheet libraries exposed through managed runtimes or scripting languages. The architectural difference is that OpenXLSX exposes native C++ workbook, worksheet, style and archive abstractions. A higher-level library may wrap those operations behind Python or C# objects, with runtime-specific packaging and easier scripting access.

That higher-level approach can simplify application development when the surrounding stack already uses that runtime. OpenXLSX is more direct for an existing native C++ codebase that already uses CMake and can manage its dependencies. It is less attractive when Excel fidelity is the primary requirement and the pending tables, filters, comments, rich text or hyperlink features are mandatory.

The README does not name or document a specific competing library, so it would be misleading to claim compatibility, speed or feature coverage against one. The actual selection boundary is the integration model and feature requirement. Native C++ control comes with dependency management and build configuration work, while a managed API can introduce runtime or deployment requirements that an existing C++ system may not want.

OpenXLSX Repository Transition and Upgrade Cost

The GitHub repository is not archived, but the README explicitly says it has been discontinued on GitHub. Development has moved to Codeberg at lars_uffmann/OpenXLSX, with plans to move it eventually to troldal/OpenXLSX. The README asks users not to open new issues or pull requests on GitHub and directs feature requests to Codeberg.

The latest listed release is v0.5.1, published on 2026-06-15. The repository's last push was also on 2026-06-15. The README identifies a development branch for functionality that has not yet reached the main repository. This distinction matters for adoption. Codeberg is the active project location, while the GitHub copy should not be used as a destination for new issues or pull requests.

OpenXLSX uses the BSD-3-Clause license. The LICENSE.md file is the authoritative project source for its terms; this article does not provide legal advice. Operationally, the larger cost is likely to come from build integration. Teams must decide between local dependencies and automatic downloads, CMake and Makefile.GNU, miniz and libzip, or shared and static configurations. The monolithic option reduces some packaging choices but works only with miniz and static dependencies.

A native C++ project can absorb that cost if it already uses CMake and vcpkg. A small application with only basic workbook needs may find a higher-level spreadsheet API easier to deploy. A feature-sensitive document processor should review the current Codeberg source before choosing OpenXLSX, especially for worksheet dimensions, Unicode paths and unsupported workbook elements.

Editorial conclusion

OpenXLSX fits C++ developers who need direct access to Excel workbooks without automating a desktop spreadsheet application. Teams that require tables, filters, true hyperlinks, XML comments or rich text should check the feature list before adoption. Projects sensitive to repository continuity should use Codeberg because the GitHub repository is discontinued, and should first verify dependency selection, worksheet dimension handling and the current build instructions.

Frequently asked questions

Official sources

1. Issues
2. License: BSD-3-Clause
3. README
4. Releases
5. troldal/OpenXLSX on GitHub