OpenXLSX

OpenXLSX

OpenXLSX is a C++ library for reading, writing, creating and modifying Microsoft Excel® files, with the .xlsx format.

The OpenXLSX project has moved to Codeberg

NOTE: With today's release v0.5.1, this repository is discontinued on github. It has been migrated to Codeberg, and will eventually be moved to @troldal's Codeberg.

Please do not open any more issues or pull requests on github, and instead submit your feature requests directly on Codeberg.

After creating an account on codeberg.org, you will be able to "own" and edit issues and comments previously created by you by linking your github account to codeberg via "Sign in with Github", direct link here.

Library Version 0.5.1

This version, with updates from 2026-06-13, is the latest release.

Table of Contents

• To-Do list
• Most recent changes
• Motivation
• Ambition
• Compatibility
• Build Instructions
  • Install cmake & git on debian-based Linux distributions
  • Install cmake & git on Windows 10/11 (for now only tested with MSYS Makefiles)
  • Build the OpenXLSX library
  • Integrating into a CMake project structure
  • Building as a separate library
• How to compile and link a program against an installed OpenXLSX library
  • Build your program using g++
  • Build your program using cmake
• Current Status
• Performance
• Caveats
  • File Size
  • Memory Usage
  • Unicode
• Reference Guide (to be written)
• Example Programs
• Changes

To-Do list

Note: generally, for features awaiting implementation, refer to the open issues in the repository

• tables/filters
• true hyperlink support
• postponed (may not be done at all): when OPENXLSX_MONOLITHIC_LIBRARY=ON, use target_link_interface instead of target_link_library for remaining dependencies (libzip/miniz, pugixml) to allow installing only monolithic library (currently the monolithic file is built, but not installed)
• XLStyles: support predefined number formats with constants that have meaningful names
• XLWorksheet: support for XML comments
• XLWorksheet: support for Rich Text elements in cell strings
• TBD: implement BUILD_SHARED_LIBS functionality in Makefile.GNU
• TBD: in Makefile.GNU, check for available dependencies and error out if any are missing

Most recent changes

For the latest functionality updates, please refer to the development branch. Feel free to have a look. This way you don't have to wait until the main repository is updated.

(aral-matrix) 13 June 2026 - major changes to cmake configuration, some minor patches

• upped OpenXLSX library version to 0.5.1 - git tag will be updated in one of the next commits
• cmake should now correctly find locally installed library versions, including determining the library type if required (OPENXLSX_MONOLITHIC_LIBRARY requires static, BUILD_SHARED_LIBS requires shared dependencies) and triggering (if enabled) automatic download from upstream if the required dependency is not available
• cmake: cleaned up debugging output, replaced message log level NOTICE with STATUS in most places since I learned that NOTICE is directed to stderr, not stdout
• XLXmlParserForwardDeclarations.hpp: added forgotten API declaration for XML namespace support
• XLDocument::create bugfix for unicode paths: use nowide functions for creating temp file, addresses #399
• XLDocument::create bugfix preventing deletion of temporary workbook template file: load document into memory, close file handle, then initialize archive from memory
• Zippy.hpp & LibZip.hpp loadArchiveData bugfix: changed fopen file mode from r to rb (binary)
• XLStyles bugfix: root XML nodes are now created (if necessary) with a sorted insertion using m_nodeOrder
• XLProperties, XLAppProperties, XLVmlDrawing, XLWorkbook bugfixes: ensure required XML namespaces of document root node
• XLWorksheet: constructor now always deletes the worksheet's tag - added void XLWorksheet::setDimension functions to set it, with auto-calculation of last cell, if desired. This addresses issue 361. Supported function overloads:

void XLWorksheet::setDimension(XLCellReference topLeft, XLCellReference bottomRight, bool autoCalculateLastCell);
void XLWorksheet::setDimension(std::string topLeft, std::string bottomRight);
void XLWorksheet::setDimension(std::string dimension);

(aral-matrix) 19 April 2026 - vcpkg compatibility maximized, some improvements/bugfixes in cmake configuration

• vcpkg support should now be as good as it gets: Big thank you to @bansan85 for maintaining the vcpkg package patches, and supporting the bugfixes / improvements of the cmake configuration so that it behaves well with vcpkg :)
• monolithic library is now available via cmake option -DOPENXLSX_MONOLITHIC_LIBRARY=ON - this requires static dependencies and only works with miniz, fails with libzip (or rather: the libzip (sub-)dependencies will not be linked into the resulting bundled library)
• for testing if a destination file exists (OpenXLSXFileSystemTools.hpp pathExists), nowide::stat is now used when nowide is in use. This should make calls to XLDocument::create and XLDocument::saveAs behave well with filenames containing unicode characters
• added function OpenXLSXFileSystemTools fileSize to wrap call to stat with nowide compatibility - this is used in LibZip.hpp loadArchiveData

Change history

Change history is found in the detailed change log.

May 2024 Update

After a long period of inactivity, I have decided to resume development of OpenXLSX. The code has been cleaned up and a significant number of bugs have been fixed. The library has been tested on Windows, macOS and Linux, and should work on all platforms.

I would like to extend my sincere thanks to all the people who have contributed to the project, either by reporting bugs, suggesting features or by submitting pull requests. I would also like to thank all the people who have starred the project, and who have shown interest in the project.

In particular, I would like to thank Lars Uffmann (https://codeberg.org/lars_uffmann/) for his contributions to the project. Lars has spent significant time and effort in cleaning up the code, fixing bugs and implementing new features. Without his help, the project would not have been in the state it is today.

20/05/2024

• Google Benchmark is no longer included in the repository. To run the benchmarks, Google Benchmark have to be installed on the system. If you use vcpkg, it will be downloaded automatically.
• Minor performance improvements to XLCellReference.

06/08/2024

• Housekeeping updates to the code.
• Added Makefile.GNU for building on Linux. The project will continue to be based on CMake, and the makefile may not always be kept up-to-date.

Motivation

Many programming languages have the ability to modify Excel files, either natively or in the form of open source libraries. This includes Python, Java and C#. For C++, however, things are more scattered. While there are some libraries, they are generally less mature and have a smaller feature set than for other languages.

Because there are no open source library that fully fitted my needs, I decided to develop the OpenXLSX library.

Ambition

The ambition is that OpenXLSX should be able to read, write, create and modify Excel files (data as well as formatting), and do so with as few dependencies as possible. Currently, OpenXLSX depends on the following 3rd party libraries:

• PugiXML
• Zippy (C++ wrapper around miniz) - an alternative wrapper for libzip can be configured with cmake option -DOPENXLSX_ENABLE_LIBZIP=ON
• (Windows only) Boost.Nowide (for opening files with non-ASCII names on Windows)

As of version 0.5.0, these libraries are no longer included in the repository, and there are three ways to build OpenXLSX against them:

1. pre-install the libraries on your operating system - the OpenXLSX cmake configuration should find them via find_package
2. auto-fetch the missing dependencies from upstream repositories, build & install them together with OpenXLSX. For this, cmake must be able to find git
3. (Windows only) install OpenXLSX via the vcpkg package manager, which handles dependencies for you:

Also, focus has been put on speed, not memory usage (although there are options for reducing the memory usage, at the cost of speed; more on that later).

Compatibility

OpenXLSX has been tested on the following platforms/compilers. Note that a '-' doesn't mean that OpenXLSX doesn't work; it just means that it hasn't been tested:

The following compiler versions should be able to compile OpenXLSX without errors:

• GCC: Version 7
• Clang: Version 8
• MSVC: Visual Studio 2019

Clang 7 should be able to compile OpenXLSX, but apparently there is a bug in the implementation of std::variant, which causes compiler errors.

Visual Studio 2017 should also work, but hasn't been tested.

Build Instructions

OpenXLSX uses CMake as the build system (or build system generator, to be exact) and git to pull in dependencies. Therefore, you must install CMake first, in order to build OpenXLSX. You can find (bad) installation instructions on www.cmake.org. If you wish the cmake to automatically fetch missing dependencies, you also need to install git.

Here is a summary to get a working configuration of cmake + git.

Install cmake & git on debian-based Linux distributions

sudo apt update
sudo apt install build-essential cmake git

Install cmake & git on Windows 10/11 (for now only tested with MSYS Makefiles)

Install MSYS2:

• In a Powershell (run as Administrator): run winget install --id MSYS2.MSYS2 -e

  → After performing this step, the "MSYS2 MSYS shell" and the "MSYS2 MinGW 64-bit shell" should be accessible from the Start Menu

• In MSYS2 MSYS shell: run pacman -Syu

  The previous instruction might require a close & reopen of the MSYS2 MSYS shell

• In MSYS2 MSYS shell: run pacman -Su

Install development toolchain:

In MSYS2 MinGW 64‑bit shell: run pacman -S --needed base-devel mingw-w64-x86_64-toolchain

Install cmake & git in MSYS2 environment:

• In MSYS2 MinGW 64‑bit shell: run pacman -S --needed mingw-w64-x86_64-cmake mingw-w64-x86_64-git
• (optional if you want to use ninja build tool instead of make) In MSYS2 MinGW 64‑bit shell: run pacman -S --needed mingw-w64-x86_64-ninja

Verify installation:

In MSYS2 MinGW 64‑bit shell: verify versions of git, cmake, gcc, g++

git --version; cmake --version; gcc --version; g++ --version

Build the OpenXLSX library

In MSYS2 MinGW 64‑bit shell

git