libxlsxwriter for C: Building Excel Files Without Spreadsheet Automation

The C Use Case Behind libxlsxwriter

libxlsxwriter addresses a specific native-development problem: generating an Excel 2007+ XLSX workbook from C without launching Excel or automating a desktop spreadsheet application. Its documented audience includes developers working with GCC, Clang, Xcode, MSVC 2015, ICC, TCC, MinGW, and MingGW-w64/32. The project also states support for Linux, FreeBSD, OpenBSD, macOS, iOS, Windows, MSYS or MSYS2, and Cygwin.

The supported workbook content is broader than a basic CSV exporter. The README lists text, numbers, formulas, hyperlinks, merged cells, defined names, autofilters, charts, data validation, dropdown lists, conditional formatting, PNG, JPEG, and GIF images, cell comments, and macro support. Formats can control presentation at workbook or cell level. This makes the library relevant to reporting tools, export functions, and back-end services whose callers expect an Excel workbook rather than a fixed text layout.

It is deliberately a creation library. The description and README both describe writing XLSX files, and neither claims support for opening or editing existing workbooks. Applications that need to inspect an existing spreadsheet, preserve unknown workbook parts, or modify a workbook in place need a different component or format. CSV may also be the better choice when recipients only need rows and columns, because it avoids a multi-file Office Open XML package and its formatting features.

Workbook, Worksheet, and Format Object Flow

The API follows an object-oriented naming pattern in C. An application first creates a workbook with `workbook_new()` and targets a filename such as `demo.xlsx`. It then obtains a worksheet through `workbook_add_worksheet()`. Worksheet pointers represent writing destinations, while a format object stores reusable presentation settings. Once cells and other objects have been added, `workbook_close()` finalizes the output.

This arrangement separates workbook lifetime from individual writes. `worksheet_write_string()` places text in a zero-based row and column, while `worksheet_write_number()` handles numeric values. The same worksheet API also accepts a format pointer, allowing application code to attach a common style without describing every cell operation again. The README example changes the first column's width with `worksheet_set_column()` and inserts an image with `worksheet_insert_image()`.

An XLSX file is a structured Office Open XML package, and the repository layout includes separate public headers under `include/`, implementation code under `src/`, bundled support libraries under `third_party/`, examples under `examples/`, and tests under `test/`. The documentation does not expose the internal ZIP assembly steps, so the public API and repository layout are the available basis for understanding the architecture. The stated runtime dependency is `zlib`, which is also one of the enabled options in the root Makefile.

For large exports, the README advertises a memory optimization mode. That changes memory consumption, not the output contract: applications still build the workbook through the library and close it after writing. The documentation does not state the exact threshold or quantify the saving, so capacity planning should be based on application-specific file size and process limits rather than an assumed improvement.

Building the Library with the Repository Makefile

The root Makefile is the clearest documented build entry point. From the repository root, build the library and its bundled third-party components with `make`. The default `PREFIX` is `/usr/local`, and `DESTDIR` is unset unless supplied. The build is quiet by default; defining `V` leaves the underlying commands visible, which can help diagnose a failed compilation.

Use the following command to perform the repository's default build. The first target runs the third-party libraries and then builds `lib/` through `src/`.

make

The README states that `zlib` is the only dependency, but the Makefile also exposes switches for using a system `minizip`, OpenSSL's MD5 implementation, the standard `tmpfile` implementation, and an optional `dtoa` library. These are build decisions, not casual style preferences. An OpenSSL-backed MD5 build adds a `libcrypto` build option, while `USE_SYSTEM_MINIZIP` changes which ZIP implementation is used.

The repository also contains `CMakeLists.txt`, `build.zig`, `Package.swift`, and a CocoaPods podspec, but the README does not give complete setup instructions for each path. This article therefore uses only the visible Makefile target rather than inventing CMake, Zig, Swift Package Manager, or CocoaPods commands.

After a successful build, the compiler must include the public header from `include/` and link the resulting library. The README gives the C example, but it does not show the complete compiler invocation, so readers should use the build instructions for their chosen compiler and installation layout.

Creating demo.xlsx Through the Public C API

The following program is the README's example. It creates `demo.xlsx`, adds a worksheet, creates one format, makes that format bold, widens the first column, writes strings and numbers, inserts `logo.png`, and closes the workbook. A successful run should leave `demo.xlsx` in the working directory. The referenced `logo.png` must also exist at the path passed to `worksheet_insert_image()`.

#include "xlsxwriter.h"

int main() {
    lxw_workbook  *workbook  = workbook_new("demo.xlsx");
    lxw_worksheet *worksheet = workbook_add_worksheet(workbook, NULL);
    lxw_format *format = workbook_add_format(workbook);

    format_set_bold(format);
    worksheet_set_column(worksheet, 0, 0, 20, NULL);
    worksheet_write_string(worksheet, 0, 0, "Hello", NULL);
    worksheet_write_string(worksheet, 1, 0, "World", format);
    worksheet_write_number(worksheet, 2, 0, 123, NULL);
    worksheet_write_number(worksheet, 3, 0, 123.456, NULL);
    worksheet_insert_image(worksheet, 1, 2, "logo.png");

    workbook_close(workbook);
    return 0;
}

The examples directory contains additional C programs for autofilters, charts, comments, array formulas, backgrounds, chart worksheets, and individual chart types. Those files are useful starting points for features that are only summarized in the README. The examples directory contains a Makefile, but its commands are not shown in the README, so a reproducible example build command cannot be stated from the documentation.

Applications should also define their own error policy around allocation and workbook creation. The short README example does not demonstrate return-value handling for every API call. The project may document fuller checks elsewhere, but that guidance cannot be inferred from the excerpt.

Format Scope and Office Feature Boundaries

The README's phrase “full Excel formatting” sits beside a more useful engineering fact: formatting is represented by `lxw_format` objects and worksheet APIs. Callers can create formats and attach them to writes, as the example does for bold text. The examples directory also contains chart formatting, chart style, chart area, background, and chart tool examples, indicating that chart presentation is handled through separate chart and format calls rather than as automatic Excel UI replication.

Not every spreadsheet requirement maps to the same abstraction. Data validation and dropdown lists are listed as library features, but generating a workbook that displays a particular existing workbook's settings requires application code to recreate those settings. Likewise, macro support means the library can add a VBA-containing workbook, but the README does not promise binary compatibility with arbitrary macro projects or an API for editing VBA logic.

The library writes XLSX, the Excel 2007+ format. It does not document the older binary `.xls` format, so an application whose contract specifically requires `.xls` would need a different output path. CSV is another useful alternative when the recipient needs plain tabular interchange rather than formatting, worksheets, validation, hyperlinks, charts, or embedded media.

The library also does not promise preservation of content produced by another spreadsheet package. Since its stated role is creation, callers should treat each run as generating a new workbook rather than loading an existing file, changing selected cells, and writing it back. This distinction affects workflows involving Excel templates.

Platform Choices, Upgrades, and Maintenance

The repository is not archived, and its last push was on 2026-07-07. Recent releases include v1.2.4 on 2026-01-12, v1.2.3 on 2025-06-30, and v1.2.2 on 2025-03-29. This supports treating the project as recently changed, but it does not by itself guarantee that every application will have a low upgrade cost. C library upgrades can require recompilation and API review across every consumer.

The root Makefile derives `VERSION` and `SOVERSION` from definitions in `include/xlsxwriter.h`. This matters when packaging the library: an installation script should not assume that the binary interface remains unchanged across releases. The repository includes ABI versioning fields, but the documentation does not explain the compatibility policy for a particular upgrade, so consumers must review `Changes.txt` and release notes for their chosen version.

The repository metadata reports a custom license category that GitHub cannot classify, while the README calls the license “FreeBSD license” and the Makefile carries `SPDX-License-Identifier: BSD-2-Clause`. The repository also contains `License.txt`. That inconsistency in classification is not enough to determine redistribution obligations. Teams should read the actual `License.txt` and any packaging terms in the repository. This is a compliance review point, not legal advice.

The top-level build files offer several integration paths, but choosing one does not remove maintenance work. A vendor embedding the source still owns updates for bundled `third_party` components and its chosen compiler or platform. A system package manager can own some of that work, but it may also package different build options. Those are concrete upgrade costs to account for before adopting the library.

libxlsxwriter Versus CSV and Read-capable Libraries

CSV is the clearest alternative when the required result is data interchange without presentation. A C application can serialize rows and columns as text, and recipients can open the result in a broad range of tools. CSV does not provide the workbook structure that libxlsxwriter supports, including multiple worksheets, charts, comments, conditional formatting, validation, images, merged cells, or defined names. It is therefore simpler for plain exports and unsuitable when those features are part of the user-facing requirement.

For editing existing XLSX files, the relevant difference is direction and scope. libxlsxwriter is documented as a library for creating XLSX output. A read-capable or read-write spreadsheet library would need to parse an existing package, locate workbook relationships, and modify stored parts while retaining the rest of the document. Those capabilities are not claimed for libxlsxwriter, so substituting it would leave the application's input problem unsolved.

For C applications generating polished Excel reports, libxlsxwriter offers a more direct route than hand-building an Office Open XML package. It also avoids the need to automate Microsoft Excel, which would bind a server-side generator to an installed desktop application. The trade-off is that developers must model workbook features through this library's object APIs and remain within its documented creation model.

The repository's many chart examples show that feature breadth extends beyond basic cells, but they also indicate a sizeable API surface. A project that needs one chart or one bold header should avoid adopting more capability than its output contract requires.

Editorial conclusion

Adopt libxlsxwriter when a C application needs direct, portable XLSX generation and can live with its write-only design and custom build choices. Do not choose it for reading or modifying existing workbooks. Before adoption, verify License.txt for the intended distribution model, test the exact output features your application needs, and confirm that the repository Makefile produces the static or shared library shape required by your build system.

Frequently asked questions

Official sources

1. Issues
2. jmcnamara/libxlsxwriter on GitHub
3. Project website
4. README
5. Releases