carboneio/carbone

⚡️ Fast, Simple and Powerful report generator in any format PDF, DOCX, XLSX, ODT, PPTX, ODS, XML, CSV using templates and your JSON data as input !

News 2026/11

Join us on our Discord

Use the latest version (v5+) for free with our Docker Edition:

  docker pull carbone/carbone-ee:latest

No license is required to start the On-Premise Docker Edition with the REST API (same API as the Cloud Edition). A license is only required for advanced features. By default, only community features are enabled.

Check out our changelog

This open-source edition, which can be embedded in Node.js, is always one major version behind. We will update it to v4 as soon as possible. Thank you for your patience.

Feel free to contact us via chat if you need further information or professional support.

Table of content

README language: 🇨🇳 简体中文, 🇺🇸 English

• Features
• How it works?
• Minimum Requirements
• Getting started
  • Basic sample
  • PDF generation, document conversion
• More examples
• API Reference
• Command line tools
• Issues
• Roadmap
• Performance
• Licenses and editions
• Philosophy
• Contributors

Features

• 🍏 Extremely simple : Create templates with LibreOffice™, Google Docs, Microsoft Office™, TinyMCE, CKEditor, ...
• 🎨 Unlimited design : The limit is your document editor: pagination, headers, footers, tables...
• 📝 Convert documents : thanks to the integrated document converter
• 📐 Unique template engine : Insert JSON-like markers {d.companyName} directly in your document
• ⭐️ Flexible : Use any XML documents as a template: docx, odt, ods, xlsx, html, pptx, odp, custom xml files...
• 🚀 Future-proof : A powerful XML-agnostic algorithm understands what to do without knowing XML document specifications
• 🌈 Multilingual : One template, multiple languages. Update translation files automatically
• 💎 Format data : Use built-in date and number formatters or create your own in Javascript
• 🏎 Fast : Manage multiple LibreOffice threads for document conversion, optimized code generation for each report

How it works?

Carbone is a mustache-like template engine {d.companyName}.

Template language documentation : https://carbone.io/documentation.html

• The template can be any XML-document coming from LibreOffice™ or Microsoft Office™ (ods, docx, odt, xslx...)
• The injected data must be a JSON object or array, coming directly from your existing APIs for example

Carbone analyzes your template and inject data in the document. The generated document can be exported as is, or converted to another format (PDF, ...) using LibreOffice if it is installed on the system. Carbone is working only on the server-side.

Minimum Requirements

• NodeJS 14.x+
• Runs on OSX, Linux (servers and desktop), and Windows

Optional

• LibreOffice server if you want to use the document converter and generate PDF. Without LibreOffice, you can still generate docx, xlsx, pptx, odt, ods, odp, html as long as your template is in the same format.
• Carbone v5 also supports Chrome and OnlyOffice converters

Getting started

Basic sample

1 - Install it

  npm install carbone

2 - Copy-paste this code in a new JS file, and execute it with node

  const fs = require('fs');
  const carbone = require('carbone');

  // Data to inject
  var data = {
    firstname : 'John',
    lastname : 'Doe'
  };

  // Generate a report using the sample template provided by carbone module
  // This LibreOffice template contains "Hello {d.firstname} {d.lastname} !"
  // Of course, you can create your own templates!
  carbone.render('./node_modules/carbone/examples/simple.odt', data, function(err, result){
    if (err) {
      return console.log(err);
    }
    // write the result
    fs.writeFileSync('result.odt', result);
  });

PDF generation, document conversion

Carbone uses efficiently LibreOffice to convert documents. Among all tested solutions, it is the most reliable and stable one in production for now.

Carbone does a lot of thing for you behind the scene:

• starts LibreOffice in "server-mode": headless, no User Interface loaded
• manages multiple LibreOffice workers to maximize performance (configurable number of workers)
• automatically restarts LibreOffice worker if it crashes or does not respond
• job queue, re-try conversion three times if something bad happen

1 - install LibreOffice

on OSX

• Install LibreOffice normally using the stable version from https://www.libreoffice.org/

on Ubuntu Server & Ubuntu desktop

Be careful, LibreOffice which is provided by the PPA libreoffice/ppa does not bundled python (mandatory for Carbone). The best solution is to download the LibreOffice Package from the official website and install it manually:

  # remove all old version of LibreOffice
  sudo apt remove --purge libreoffice*
  sudo apt autoremove --purge

  # Download LibreOffice debian package. Select the right one (64-bit or 32-bit) for your OS.
  # Get the latest from http://download.documentfoundation.org/libreoffice/stable
  # or download the version currently "carbone-tested":
  wget https://downloadarchive.documentfoundation.org/libreoffice/old/7.5.1.1/deb/x86_64/LibreOffice_7.5.1.1_Linux_x86-64_deb.tar.gz

  # Install required dependencies on ubuntu server for LibreOffice 7.0+
  sudo apt install libxinerama1 libfontconfig1 libdbus-glib-1-2 libcairo2 libcups2 libglu1-mesa libsm6

  # Uncompress package
  tar -zxvf LibreOffice_7.5.1.1_Linux_x86-64_deb.tar.gz
  cd LibreOffice_7.5.1.1_Linux_x86-64_deb/DEBS

  # Install LibreOffice
  sudo dpkg -i *.deb

  # If you want to use Microsoft fonts in reports, you must install the fonts
  # Andale Mono, Arial Black, Arial, Comic Sans MS, Courier New, Georgia, Impact,
  # Times New Roman, Trebuchet, Verdana,Webdings)
  sudo apt install ttf-mscorefonts-installer

  # If you want to use special characters, such as chinese ideograms, you must install a font that support them
  # For example:
  sudo apt install fonts-wqy-zenhei

2 - generate PDF

And now, you can use the converter, by passing options to render method.

Don't panic, only the first conversion is slow because LibreOffice must starts Once started, LibreOffice stays on to make new conversions faster

  var data = {
    firstname : 'John',
    lastname : 'Doe'
  };

  var options = {
    convertTo : 'pdf' //can be docx, txt, ...
  };

  carbone.render('./node_modules/carbone/examples/simple.odt', data, options, function(err, result){
    if (err) return console.log(err);
    fs.writeFileSync('result.pdf', result);
    process.exit(); // to kill automatically LibreOffice workers
  });

More examples

Nested repetition in a docx document and spreadsheet

  var data = [
    {
      movieName : 'Matrix',
      actors    : [{
        firstname : 'Keanu',
        lastname  : 'Reeves'
      },{
        firstname : 'Laurence',
        lastname  : 'Fishburne'
      },{
        firstname : 'Carrie-Anne',
        lastname  : 'Moss'
      }]
    },
    {
      movieName : 'Back To The Future',
      actors    : [{
        firstname : 'Michael',
        lastname  : 'J. Fox'
      },{
        firstname : 'Christopher',
        lastname  : 'Lloyd'
      }]
    }
  ];

  carbone.render('./node_modules/carbone/examples/movies.docx', data, function(err, result){
    if (err) return console.log(err);
    fs.writeFileSync('movies_result.docx', result);
  });

  carbone.render('./node_modules/carbone/examples/flat_table.ods', data, function(err, result){
    if (err) return console.log(err);
    fs.writeFileSync('flat_table_result.ods', result);
  });

API Reference

To check out the api reference and the documentation, visit carbone.io.

Command line tools

To checkout out the Carbone CLI documentation, visit carbone.io

Issues

If you're facing any issues with this Community Edition, search a similar issue to ensure it doesn't already exist on Github. Otherwhise, create an issue to help us.

Roadmap

The roadmap is pinned on the github issues list.

Performance

⚡️ Our own PDF converter, Carbone ICE (Instant Converter Engine), is now available. It is much faster than LibreOffice. Select it with the converter option set to "I".

A public benchmark, including the API and the Docker image, is available here: document-generator-benchmark.

Results for a one-page DOCX invoice (carbone/carbone-ee:full-5.15.0, Apple M4 Max, September 2026):

Invoice DOCX	Documents / min (1 CPU, 1 VU)	Documents / min (4 CPU, 5 VU)	Pages / s (large documents)
DOCX → DOCX (merge only)	10,302 (7.5 ms)	17,871 (24 ms)	1,059
DOCX → PDF Carbone ICE	2,842 (24 ms)	13,856 (29 ms)	141
DOCX → PDF LibreOffice	1,144 (60 ms)	5,796 (63 ms)	5
DOCX → PDF OnlyOffice	245 (249 ms)	934 (434 ms)	26

Another public benchmark compares pure document conversion (DOCX → PDF, HTML → PDF) with other free converters (Gotenberg, Collabora, Jod-converter, Pandoc): document-converter-benchmark. It uses the free Community Edition of the Carbone Docker image, no license required. With 4 threads, Carbone converts a DOCX to PDF in ~17 ms with Carbone ICE (~400 ms with Gotenberg, which runs LibreOffice on a single thread), and an HTML to PDF in ~8 ms (~375 ms with Gotenberg).

Older measurements of this npm package (carbone v3), kept for reference: they were made on older hardware and are a bit outdated. See the benchmarks above for up-to-date figures.

Report generation speed (without network latency), using a basic one-page DOCX template:

• ~ 10 ms / report without document conversion (analyzing, injection, rendering)
• ~ 50 ms / report with a PDF conversion (100 loops, 3 LibreOffice workers, without cold-start)

On a MacBook Pro Mid-2015, 2,2 Ghz i7, 16Go.

Licenses and editions

There are two editions of Carbone:

• Carbone Community Edition (this source code and the npm package carbone) is source-available and freely available under the Carbone Code License (CCL). Roughly speaking, as long as you are not offering the Carbone source code as a hosted Document-Generator-as-a-Service like Carbone Cloud, and you are not building a competing document generator with it, you can use all Community features for free, inside your own products. See which license applies to each edition.
• Carbone Enterprise Edition (hosted and on-premise) includes additional features. Here is a high-level comparison table of community and enterprise features.

The Community Edition is one major version behind the Enterprise Edition. This rule may change in the future.

Philosophy

Our ultimate goal

2% percent of our hosted solution revenues goes to charity

Contributors

Thanks to all Carbone contributors (random order)

• Florian Bezagu
• Matthieu Robin
• Arnaud Lelièvre
• Maxime Vincent
• Enzo Ghemard
• Jordan Nourry
• Etienne Rouillard
• Guillaume Chevaux
• Fabien Bigant
• Maxime Magne
• Vincent Bertin
• Léo Labruyère
• Aurélien Kermabon
• Steeve Payraudeau