Flying Saucer: a pure-Java CSS 2.1 renderer that picks its own contribution model

A CSS 2.1 engine, not a browser in disguise

The repository description is precise: an XML/XHTML and CSS 2.1 renderer in pure Java. That combination of words explains both the strength and the limit of this library.

Flying Saucer takes arbitrary well-formed XML, or XHTML, lays it out using CSS 2.1, and writes the result to Swing panels, PDF, or images. Because it is pure Java with no browser dependency, you can run it in a servlet, a batch job, or a serverless function without shipping Chromium alongside it. For generating an invoice or a report from a document that is already valid XHTML, that is exactly the shape you want.

The alternative approaches each make a different trade. A headless Chrome gives you full CSS3 and HTML5 at the cost of a large binary and a slow start. iText and OpenPDF give you precise PDF control but no CSS at all, so you build layout programmatically. Flying Saucer sits between them: real CSS, real pagination, and a JVM footprint measured in megabytes rather than hundreds.

The output side is where the pieces live in the tree. flying-saucer-core holds the layout engine and Java2D rendering, flying-saucer-pdf handles PDF through OpenPDF, flying-saucer-swt covers SWT, and flying-saucer-examples holds the sample code the README points you at for getting started.

There is also flying-saucer-fop, which is not in the Maven list the README gives, and flying-saucer-pdf-osgi for OSGi environments. Worth knowing about if your deployment is bundle-based.

Six artifacts, and one of them replaces a browser

The README lists the artifacts explicitly, and the list explains a lot about the project's direction:

- `org.xhtmlrenderer:flying-saucer-core`, the core library and Java2D rendering - `org.xhtmlrenderer:flying-saucer-pdf`, PDF output using OpenPDF - `org.xhtmlrenderer:flying-saucer-pdf-openpdf`, described as not supported anymore and replaced by `flying-saucer-pdf` - `org.xhtmlrenderer:flying-saucer-chrome-pdf`, PDF output by delegating to `chrome-headless-shell`, noted as supporting modern HTML5 and CSS3 - `org.xhtmlrenderer:flying-saucer-swt` for SWT output - `org.xhtmlrenderer:flying-saucer-log4j` as a logging plugin

That chrome-pdf entry arrived in version 10.3.0 and is the most consequential thing in the recent history. It is the project admitting, in its own artifact list, that CSS 2.1 is not always enough, and offering a path forward that trades the pure-Java property for standards coverage. Existing users keep the core engine; new users with modern markup start there.

The deprecated pdf-openpdf artifact is a smaller migration note. If you depend on it, move to flying-saucer-pdf.

Java requirements have moved three times and are stated as a clean progression. Version 9.5.0 and later require Java 11, 9.6.0 requires Java 17, and 10.0.0 requires Java 21. If you are on an older runtime, the last version you can use is pinned by which of those lines you fall under, and the jump to 21 is the one that will affect enterprise environments most.

GitHub issues are off, and the README explains why

This is the most distinctive thing about the project, and no other entry in this batch does anything like it. The README has a PROJECT STATUS section that quotes the merge and release policy directly.

The policy, as written: if you create a pull request that can merge without conflicts, the maintainer will merge it. Additional changes or feedback may be requested, but the expectation is that they will be extremely rare. The stated contract is that if you are still using Flying Saucer, need something changed, and are willing to do the work yourself, the change will be accepted and released. Releases are bundled roughly every four to six months unless someone asks for one sooner.

And then the consequence: issues are currently deactivated on GitHub, and the README says that this policy is the reason.

That is a coherent design rather than neglect. A library with a two-person core team and 36 open issues would otherwise accumulate unbounded triage, and this way every change arrives pre-solved. The cost is real: you cannot report a bug and wait, you cannot ask whether something is a bug at all, and the Google group at groups.google.com/g/flying-saucer-users is where discussion actually happens.

If you are evaluating this library, that model is part of the evaluation. It works well if you are willing to send a patch. It does not work if you need a maintainer to triage on your behalf.

PDF/A compliance and accessibility in the 10.5 release

Version 10.5.0, published on 2026-08-17, is the release that moves this project in a new direction. Its first item makes PDFs generated by Flying Saucer compatible with the PDF/A-1 and PDF/A-3 ISO standards.

That matters more than a typical feature line. PDF/A is the archival format, the one that is required for long-term document retention and for many government and regulated submission pipelines. A library that previously produced a PDF nobody could archive can now produce one they can.

The second item is accessibility, and it is unusual to see it listed this way. Seven separate pull requests, numbered 704 through 711, are bundled into the accessibility support entry, which is what a cross-cutting feature looks like when it touches tagging, structure, and alternate text throughout the renderer.

The rest of 10.5.0 is smaller but concrete. The chrome-pdf module gained a warmup method that pre-downloads and verifies the Chrome browser, which addresses the cold start that makes headless browser rendering awkward in a serverless function. Support for the letter-spacing and word-spacing CSS properties landed by way of a first-time contributor. A fix resolves percentage min and max width on table cells against the table's own width, and another fixes server-relative URLs when they appear against a synthetic inline stylesheet URI.

That last pair is the kind of bug that only shows up in real deployments, where the document references resources through a base URI the renderer assembled itself.

Modern CSS is arriving one property at a time

Between versions 10.3.0 and 10.5.0, the theme is a project working its way toward contemporary CSS without abandoning the CSS 2.1 architecture.

Version 10.4.0 from 2026-07-16 adds CSS transform and transform-origin support in PDF output, plus inline svg elements in PDF, and fixes an SVG detection case where the prolog opens with a comment. It also honours box-sizing: border-box for display: table-cell, which matters for anyone whose column widths silently disagree with their CSS. A security fix hardens DocumentBuilderFactory usage against XXE, which is worth noting because any library that parses XML is a candidate for that class of problem.

Version 10.3.0 from 2026-06-09 introduced the chrome-pdf module and added support for the :has pseudo class and multi-column layout, both by a first-time contributor. It also bumped OpenPDF from 3.0.4 to 3.0.5 through Dependabot.

One small but useful signal from 10.4.0: unsupported CSS features are now logged under a dedicated logger name, Html5Support. That gives you a way to find out what your document is losing during rendering without diffing the PDF by eye, which is the kind of diagnostic that turns a rendering mystery into a ten-minute fix.

Taken together, the three releases show a project that is adding capability in the core engine while admitting that the hard cases now live in the Chrome-backed module.

Entry points, licence, and where the documentation actually is

The README's getting started section is brief and points at the flying-saucer-examples directory. Three of the named entry points are the ones you will actually reference:

org.xhtmlrenderer.simple.XHTMLPanel
org.xhtmlrenderer.pdf.PDFRenderer
org.xhtmlrenderer.simple.ImageRenderer

There is also a browser demo started by org.xhtmlrenderer.demo.browser.BrowserStartup, which is the fastest way to see rendering behave on your own markup before writing any integration code. For the build path you need flying-saucer-core, flying-saucer-pdf, and flying-saucer-swt, plus the SWT JAR for your operating system.

The licence is the LGPL, version 2.1 or later, and the README is unusually explicit that you can use Flying Saucer in any way and for any purpose as long as you respect the terms. Copies of LGPL 2.1 and 3 ship in the distributions and the source tree, alongside GPL variants. The LICENSE file additionally lists the FOSS packages Flying Saucer depends on with their individual licences, which is what you want when your compliance process asks about transitive dependencies. The repository carries no licence field, so the LICENSE files in the tree are the authoritative answer.

For documentation, the README links The Flying Saucer User's Guide, and the repository carries doc/, www/, notes/, tests/, and a LICENSE-W3C-TEST directory that suggests conformance testing against the W3C test suite. The doc folder plus the R8 guide reference implies the prose documentation has not been rewritten for the 10.x line, so expect to read the guide for concepts and the release notes for current behaviour.

Editorial conclusion

Flying Saucer is a good fit when you need a server-side PDF from well-formed XML and you do not want a browser in the pipeline. The pure-Java CSS 2.1 engine is mature, version 10.5.0 added PDF/A-1 and PDF/A-3 conformance plus accessibility work, and the PDF artifact works against OpenPDF. Two things to weigh first. Java 21 is required from version 10.0.0, a real jump for anyone on an older runtime. And CSS 2.1 is the ceiling, so for HTML5 and CSS3 the project now ships flying-saucer-chrome-pdf, which delegates to chrome-headless-shell and gives up the no-browser property. Note that GitHub issues are switched off by design: the documented path is a pull request you are willing to finish yourself, reviewed through the Google group.

Frequently asked questions

Official sources

1. flyingsaucerproject/flyingsaucer on GitHub
2. Issues
3. README
4. Releases