Here are some instructions to get you up and running with the libxlsxwriter library on different OSes.

Installation on Linux

Quick-start on Linux

If you prefer to assemble Ikea furniture first and only read the instructions when you have parts left over then the following minimal set of commands should get you up and running on a Debian like system:

sudo apt-get install -y zlib1g-dev
git clone https://github.com/jmcnamara/libxlsxwriter.git
cd libxlsxwriter
make
sudo make install

If you read instructions first and then assemble the furniture you will know how to proceed.

Install the dependencies

The only dependency (apart from testing dependencies) is Zlib version 1.2.8.

The easiest way to install zlib is from the source code:

curl -O -L  http://zlib.net/fossils/zlib-1.2.8.tar.gz
tar zxf zlib-1.2.8.tar.gz
cd zlib-1.2.8

./configure
make

sudo make install

Alternatively, you can use your OS packager to install the zlib development libraries. For example:

sudo apt-get install -y zlib1g-dev

However, you need to ensure that the version installed is 1.2.8 or you will get zlib related compilation issues.

Get the source code via Git

Clone the libxlsxwriter source code repository from GitHub as follows:

git clone https://github.com/jmcnamara/libxlsxwriter.git
# Or use your preferred protocol instead of https.

Get the source code as a tarball

If you prefer you can get a tarball of the latest code as follows:

curl -O -L http://github.com/jmcnamara/libxlsxwriter/archive/master.tar.gz

Build the source code

Build the source code as follows:

cd libxlsxwriter
make

This will create a static and dynamic library in the local ./lib directory:

ls lib
libxlsxwriter.a     libxlsxwriter.so

To see a verbose summary of the compilation steps use V=1:

make V=1

Try an example

If there weren't any warnings or errors in the previous step (and there shouldn't have been) then you can build the programs in the examples directory and try one of them out:

make examples
./examples/hello

This will create a hello_world.xlsx file in your current directory. Open the file in a spreadsheet application. The output should look like this:

There is a large range of tests that you can run but they have some additional dependencies. If you are interested see Running the Test Suite.

Install the library

Libxlsxwriter supports a simplified installation scheme for a static and dynamic/shared library and header files.

sudo make install

The files are installed to /usr/local by default but this can be overridden by using the INSTALL_DIR environmental variable:

make install INSTALL_DIR=/usr/third_party

This installation method isn't fool proof but if it fails on your system you will probably know exactly how to fix it or have no idea how to fix it. I'm hoping for the former.

Using the library

Using you favourite editor create a file like the following called myexcel.c:

#include "xlsxwriter.h"
int main() {
    lxw_workbook  *workbook  = workbook_new("myexcel.xlsx");
    lxw_worksheet *worksheet = workbook_add_worksheet(workbook, NULL);
    int row = 0;
    int col = 0;
    worksheet_write_string(worksheet, row, col, "Hello me!", NULL);
    return workbook_close(workbook);
}

If you executed the "make install" command in the previous section then you should be able to compile the program as follows:

cc myexcel.c -o myexcel -lxlsxwriter

In some environments, or if you changed the INSTALL_DIR location, you may have to provide explicit include and lib paths:

cc myexcel.c -o myexcel -I/usr/local/include -L/usr/local/lib -lxlsxwriter

This will create an executable that you can run to generate an Excel spreadsheet:

./myexcel
xdg-open myexcel.xlsx

If the installation didn't work for you then you can link against the static library you created in the "Build the source code" step:

cc myexcel.c -o myexcel -I /path/to/libxlsxwriter/include \
                           /path/to/libxlsxwriter/lib/libxlsxwriter.a -lz

Installation on FreeBSD and OpenBSD

Installation on FreeBSD and OpenBSD is mainly the same as on Linux, see above, with the differences outlined below.

Both FreeBSD and OpenBSD come with the zlib development libraries pre-installed so there are no additional dependencies. However, if you have any issues then follow the instructions to install zlib.

Get the source code via Git or get the source code as a tarball as shown above then build the source code as follows using gmake (not make):

cd libxlsxwriter
gmake

Then follow the instructions in the Linux section to install the library and use the library.

Installation on macOS and iOS

The instructions for installing on Linux, shown above, will also work on macOS.

To install for Xcode and iOS use the Cocoa Pods method shown in the next section.

On macOS you can also use brew/homebrew, see below.

Install using Cocoa Pods for Xcode

For iOS and macOS projects in Xcode you can install libxlsxwriter using CocoaPods.

For a sample Xcode project that uses the libxlsxwriter cocoapod for iOS and macOS with Objective-C and Swift see libxlsxwriter Cocoa Examples, provided by Ludovico Rossi.

Installation on macOS with homebrew

On macOS you can also use brew/homebrew:

brew install libxlsxwriter

# Once installed you can compile and run a libxlsxwriter program as follows.
cc myexcel.c -o myexcel -I/usr/local/include -L/usr/local/lib -lxlsxwriter
./myexcel

Install using CMake

Libxlsxwriter also supports CMake for building and installing the library, as follows:

cmake $SOURCE_DIR $FLAGS

For example:

cd cmake
cmake ..
make
make install

Note: The CMake build system is currently experimental and should be considered as a secondary build system. The make build system described in the previous sections should be used in preference when integrating libxlsxwriter with applications or packaging.

CMake Flags

Certain build features can be controlled by passing flags to Cmake. For example:

cd cmake
cmake .. -DBUILD_TESTS=ON
make
make check_xlsxwriter_unit

Some of the Libxlsxwriter specific flags are:

BUILD_STATIC: Build static libraries (default on). To build shared libraries, pass -DBUILD_STATIC=OFF during configuration.
BUILD_EXAMPLES: Build example files (default off). To build the examples, pass -DBUILD_EXAMPLES=ON during configuration.
BUILD_TESTS: Build unittests (default off). To build the unittests, pass -DBUILD_TESTS=ON during configuration.
ZLIB_ROOT: The ZLIB root directory can be specified either through an environment variable (export ZLIB_ROOT=/usr/include) or using a flag with CMake (-DZLIB_ROOT:STRING=/usr/include). This sets the preferred search path for the ZLIB installation.

CMake Options

CMake sets debug and release builds with the CMAKE_BUILD_TYPE option. To build in release mode, pass -DCMAKE_BUILD_TYPE=Release during configuration.

CMake Generators

CMake also supports custom build generators, such as Makefiles, Ninja, Visual Studio, and Xcode. For example, to generate a Visual Studio solution, configure with:

cmake .. -G "Visual Studio 14 2015 Win64"

For more information on using generators see: cmake-generators.

Building an app with Cmake and Microsoft Visual Studio

Open a Windows CMD or Command Window and set up your MSVC environment, if required.

Then create a work directory and and an install directory that the include and library files will be installed to. Set the follow variables to point to the directories:

set    WORK_DIR=C:/Users/Username/tmp
set INSTALL_DIR=C:/Users/Username/tmp/install_dir

Build the Zlib library:

cd %WORK_DIR%

git clone https://github.com/madler/zlib.git
cd zlib
mkdir build
cd    build

cmake .. -G "Visual Studio 14 Win64" -DCMAKE_INSTALL_PREFIX:PATH="%INSTALL_DIR%/zlib"

cmake --build . --config Release --target install

Build the libxlsxwriter library:

cd %WORK_DIR%

git clone https://github.com/jmcnamara/libxlsxwriter.git
cd libxlsxwriter
mkdir build
cd    build

cmake .. -G "Visual Studio 14 Win64" -DCMAKE_INSTALL_PREFIX:PATH="%INSTALL_DIR%/libxlsxwriter" -DZLIB_ROOT:STRING="%INSTALL_DIR%/zlib"

cmake --build . --config Release --target install

Create a new Win32 Console (or other C/C++) application in Visual Studio:

File
  -> New
    -> Project

Visual C++
  -> Win32
    -> Win32 Console Application

Change the ARCH in the main Dialog to "x64" (or to match the parameter to cmake).

Replace the empty main with a libxlsxwriter example, make sure to include "stdafx.h" and "xlsxwriter.h":

#include "stdafx.h"
#include "xlsxwriter.h"
int main() {
    lxw_workbook  *workbook = workbook_new("hello_world.xlsx");
    lxw_worksheet *worksheet = workbook_add_worksheet(workbook, NULL);
    worksheet_write_string(worksheet, 0, 0, "Hello", NULL);
    worksheet_write_number(worksheet, 1, 0, 123, NULL);
    workbook_close(workbook);
    return 0;
}

Edit the application properties:

Project
  -> ConsoleApplication Properties

Set the libxlsxwriter include path to match the path used above:

Configuration Properties
  -> C/C++
    -> General
      -> Additional Include Directories

Set it to the following (or similar path used above):

C:\Users\Username\tmp\install_dir\libxlsxwriter\include

Set the linker directories to match the path created above:

Configuration Properties
  -> Linker
    -> General
      -> Additional Library Directories

Add the following (or similar paths used above):

C:\Users\Username\tmp\install_dir\libxlsxwriter\lib\x64\Release
C:\Users\Username\tmp\install_dir\zlib\lib

Set the linker additional libraries to match the zlib and xlsxwriter libs created above:

Configuration Properties
  -> Linker
     -> Input
        -> Additional Dependencies

Add the following:

xlsxwriter.lib
zlib.lib

Build the solution and run the output executable. It should create a hello_world.xlsx file in the same directory you ran it from.

Installation on Windows using Microsoft Visual Studio

As an alternative to the Cmake option shown above there is a complete sample Microsoft Visual Studio project on GitHub called MSVCLibXlsxWriter.

The allows you to build a DLL of libxlsxwriter and also a sample application that uses it to create an Excel output file.

Building a Windows DLL of libxlsxwriter

The MSVCLibXlsxWriter repository contains 3 directories:

LibXlsxWriterProj: A MSVC project to build a LibXlsxWriter.dll from the libxlsxwriter source code. The directory also contains a pre-built Zlib.dll file.
ExampleExe: A libxlsxwriter sample application built as a console application that requires the LibXlsxWriter.dll and Zlib.dll files.
libxlsxwriter: The libxlsxwriter source code in a git submodule, see below.

The libxlsxwriter directory is a Git submodule. This means that it isn't included when you do a standard Git clone of MSVCLibXlsxWriter. In order to get the submodule as well as the project code you must clone the project recursively as follows:

git clone --recursive https://github.com/jmcnamara/MSVCLibXlsxWriter.git

Or update it explicitly as follows:

git clone https://github.com/jmcnamara/MSVCLibXlsxWriter.git
cd MSVCLibXlsxWriter/
git submodule init
git submodule update

To build the DLL of the library open the LibXlsxWriterProj/LibXlsxWriter.sln project in MS Visual Studio and build the solution using the "Build -> Build Solution" menu item.

In the default configuration this will build an x64 debug LibXlsxWriter .lib and .dll in:

MSVCLibXlsxWriter\LibXlsxWriterProj\x64\Debug

Building a console application using the LibXlsxWriter.lib

Ensure that LibXlsxWriter.lib was built correctly in the previous steps.

To build the example executable open the ExampleExe/ExampleExe.sln project in MS Visual Studio and build the solution using the "Build -> Build Solution" menu item.

In the default configuration this will build the following x64 exe file:

MSVCLibXlsxWriter\ExampleExe\x64\Debug\ExampleExe.exe

To run the application copy the LibXlsxWriter.dll and Zlib.dll files from the MSVCLibXlsxWriter\LibXlsxWriterProj sub-directories to the same directory as the executable. You can then run the application by double clicking on it in File Explorer or by opening a CMD console and running it from the directory.

Once the program has run it will create a chart_column.xlsx file based on the default sample application in ExampleExe.cpp. You can run other libxlsxwriter example programs by copying the code from one of the libxlsxwriter\example\*.c programs.

Specifying a TEMP directory for libxlsxwriter

The libxlsxwriter library creates temporary files in the system TEMP directory during assembly of an xlsx file. On Windows this directory may not be writeable by a libxlsxwriter application (although it will try several TEMP locations before returning an error). To work around this you can set the tmpdir parameter of the lxw_workbook_options struct and pass it to workbook_new_opt():

lxw_workbook_options options = {.constant_memory = LXW_FALSE,
                                .tmpdir = "C:\\Temp"};
lxw_workbook  *workbook  = workbook_new_opt("filename.xlsx", &options);

This can also be used on Unix systems where the TEMP directory isn't writeable.

The TEMP file handling with optional temporary directory support is provided by the Tmpfileplus library which is included in the source tree. If you wish to use the standard library tmpfile() function instead you can compile without tmpfileplus as follows:

make USE_STANDARD_TMPFILE=1

Note: When using the the standard library tmpfile() the tmpdir parameter, shown above, is ignored.

Installation on Windows using Mingw-w64 and MSYS2

The libxlsxwriter library can also be compiled on Windows using the Mingw-w64 "Minimalist GNU for Windows" toolchain. These tools can be run from the Windows cmd.exe but it is recommended to use the MSYS2 "Minimal System" Bourne Shell.

Here are some instructions on how to compile libxlsxwriter with Mingw-w64 and MSYS2:

# Install MSYS2 64 or 32 bit from http://msys2.github.io/

# Install the dev tools for libxlsxwriter.
pacman -S git gcc make zlib-devel

# Clone and build libxlsxwriter.
git clone https://github.com/jmcnamara/libxlsxwriter.git
cd libxlsxwriter/
make

After compilation you can follow the instructions in the Install the library and Using the library sections above. When using the library you may also need to link against the zlib library using -lz:

gcc myexcel.c -o myexcel -lxlsxwriter -lz

It is also possible to use Cygwin and the older MinGW and MSYS. Libxlsxwriter has been confirmed to compile and work in all of these environments.

Linking against system minizip

Libxlsxwriter uses the minizip component of Zlib to create the xlsx zip file container. The source files for minizip are included in the src tree of libxlsxwriter and are statically linked by default.

If you have a lminizip library already installed on your system and prefer to dynamically link against that you can use the following compilation option:

make USE_SYSTEM_MINIZIP=1

Compiling on Big Endian Architecture

Libxlsxwriter can be compiled on a big endian system as follows:

make USE_BIG_ENDIAN=1

Next steps

If you got libxlsxwriter built and working successfully then the next sections will look at how to create some more in-depth examples.

Next: Tutorial 1: Create a simple XLSX file

Table of Contents