DEV Community

Dipsac
Dipsac

Posted on

Converting draw.io files to PDF — the CLI way and the lazy way

#webdev #devops #showdev #productivity

Every team I've worked with keeps architecture diagrams in draw.io, and every team eventually hits the same question: how do we get clean PDFs out of these files — ideally in CI?

Here's what actually works in 2026.

The CLI way (for pipelines)

draw.io Desktop ships a headless export mode. On a machine with a display server:

drawio -x -f pdf -o output.pdf input.drawio
Enter fullscreen mode Exit fullscreen mode

In CI you need a virtual display, so wrap it with xvfb:

xvfb-run drawio -x -f pdf -o output.pdf input.drawio
Enter fullscreen mode Exit fullscreen mode

Or skip the setup entirely and use the community Docker image:

docker run -v $(pwd):/data rlespinasse/drawio-export
Enter fullscreen mode Exit fullscreen mode

This renders every page of the file to PDF. It's the right answer for automated builds — reproducible, versionable, no manual steps.

Two gotchas I hit:

  • Some CLI builds choke on compressed .drawio files (the default save format embeds deflated XML). If exports come out empty, uncompress the file first (File → Properties → uncheck "Compressed" in the editor).
  • Page sizing: without --crop you get the configured page size, not the diagram bounds, so wide diagrams get cut or padded.

The lazy way (for everything else)

For one-off conversions — checking output before committing, exporting a file someone emailed you, batch-converting a folder of diagrams — spinning up Docker is overkill.

I built a free browser tool for exactly this: it does server-side conversion to vector PDF, handles compressed .drawio files that CLI builds reject, renders each page at its own size (no blank interleaves), and takes up to 10 files in a batch:

https://dipsac.com/tools/pdf-tools/convert-drawio-to-pdf-online

Disclosure: it's my tool. Free, no signup, files are deleted after processing. There's also a Russian/Spanish/Portuguese version if your team isn't English-first.

Which one when

  • CI/CD, repeatable builds → drawio CLI or the Docker image
  • One-offs, compressed files, quick checks, non-dev teammates → browser tool
  • Need SVG/PNG instead → the CLI does both with -f svg / -f png

If you've found a cleaner way to handle compressed files in the CLI, tell me in the comments — that's the one wart I never fixed properly.

Top comments (0)