[Conversion Output] kfxgen - open-source python KFX generator

[jloutsch]

Hi everyone, I'm happy to share a plugin I've been working on since last December.

kfxgen is an open-source Calibre output plugin that generates Kindle KFX files natively in Python — without invoking Amazon's Kindle Previewer. It produces a working in-book table of contents and Kindle navigation pane, and has been tested on Kindle hardware. It also shows images across the books I've tested.

I'm posting it here for others to try and review. Feedback, bug reports, and corrections are very welcome.

A few things up front:

• License: GPL v3.
• Credit / derivation: the KFX serialization code (the kfxlib_minimal directory) is a modified subset of John Howell's kfxlib from his KFX plugins, used under the GPL v3 it's licensed under. Full attribution is in the NOTICE file (shipped inside the plugin zip and in the repo). Thanks to jhowell — this wouldn't exist without that work.
• No DRM involved: kfxgen converts EPUBs you already have into KFX. It does not remove, bypass, or interact with DRM in any way.

Why another KFX plugin
The official KFX Output plugin depends on Kindle Previewer, which is closed-source, Windows/Mac-only (Linux needs Wine), and takes minutes per book. kfxgen runs in pure Python, converts in seconds, works anywhere Calibre runs, and needs no external binaries.

The main reason I built it: custom fonts that actually render. KFX honors the font you've selected on the Kindle — including custom fonts you've installed on the device — and applies that font's OpenType features (ligatures, contextual alternates), which AZW3/MOBI didn't do reliably for me. kfxgen writes override_kindle_font: false so the device font is respected rather than overridden. Note: the font lives on the Kindle, not in the file — kfxgen does not embed font files, so the custom font must be installed on the device.
Building kfx output files via the kindle previewer was slow, and this method drastically speeds up the process.

How it relates to jhowell's "KFX Output"
This is a separate, independent plugin. In Calibre's plugin list it appears as kfxgen (not "KFX Output"). Because both produce the same KFX output format, only one can own the KFX conversion slot at a time — if you have both installed, enable just one. kfxgen is intended as a faster, dependency-free alternative for people who want it; jhowell's plugin remains the reference.

Validation
Every release runs a full pytest suite in CI and is exercised against a 90-book public-domain Project Gutenberg corpus (English, German, Dutch, Latin, Beowulf/Odyssey, heavily illustrated books, the Complete Works of Shakespeare with 1,169 TOC entries, etc.) with per-book correctness metrics. Output has been checked on Kindle devices.

Requirements

• Calibre 5.0 or newer
• Windows, macOS, or Linux

Install

1. Download kfxgen-plugin-5.3.18.zip from the latest release: https://github.com/jloutsch/kfxgen/releases/latest
2. Calibre → Preferences → Plugins → Load plugin from file → select the zip.
3. Restart Calibre.
4. Convert any book with Output format set to KFX.

Command line:

calibre-customize -a kfxgen-plugin-5.3.18.zip

Known limitations

• On verse-heavy or image-heavy books, the Calibre conversion path can retain slightly less text than the direct-Python path (Calibre's OEB pipeline normalizes line breaks and alt-text differently).
• TOC entries that jump within a single file via #anchor (e.g. dictionary A/B/C sub-entries) appear as separate chapters rather than in-page anchors. Reading order and content are preserved.
• Fonts are not embedded in the file. Custom fonts render via the font installed on the Kindle (see above) — by design, but it means the font must be on the device.
• Inline emphasis (italic / bold within a paragraph) and most source CSS typography are not yet carried through; paragraph-level styles (font size, line height, alignment, margins, headings) are. KFX supports a subset of CSS, so this is a coverage gap rather than a hard limit — tracked in [#9](https://github.com/jloutsch/kfxgen/issues/9).

I leaned heavily on jhowell's kfx input and kfx output to create this successfully, so many thanks to jhowell!

The plugin may be downloaded here.

The main page is here along with tests and security review information: https://github.com/jloutsch/kfxgen

Tests available here

[kovidgoyal]

Good work. If you are willing to lift the no font embedding limitation I might be willing to merge your plugin into calibre, making it a builtin plugin after it has matured a bit and seen some testing via users.

[JSWolf]

You really should properly embed this plugin in your first post like all the other plugins that calibre knows of. make it so the plugin can eventually be installed with calibre.

[jloutsch]

Originally Posted by kovidgoyal

Good work. If you are willing to lift the no font embedding limitation I might be willing to merge your plugin into calibre, making it a builtin plugin after it has matured a bit and seen some testing via users.

My opinion was that KFX can display any custom fonts installed on the kindle, which would negate the need to embed fonts?

[jloutsch]

Originally Posted by JSWolf

You really should properly embed this plugin in your first post like all the other plugins that calibre knows of. make it so the plugin can eventually be installed with calibre.

I see that other posts have a zip file attached - is this what you mean by embed?

[theducks]

Originally Posted by jloutsch

I see that other posts have a zip file attached - is this what you mean by embed?

Yes.
Beta posts are inline as they are created, then moved to post #1 or removed as relevant after user testing.
You can't edit posts yet as your post count is too low. A forum mod can move to post 1 as needed until then.

[JSWolf]

Originally Posted by jloutsch

My opinion was that KFX can display any custom fonts installed on the kindle, which would negate the need to embed fonts?

A lot of eBooks have embedded fonts. So if you want them, they need to be allowed. KFX supports embedded fonts. So your plugin needs to support embedded fonts.

Are you going to be able to keep up with any changes Amazon makes to KFX?

[jhowell]

My interest in KFX is mostly in discovering how it works and converting from it to other formats. The KFX Output plugin was originally created to allow me to experiment with the Kindle Previewer's conversion to KPF/KFX in order to reverse engineer different aspects of that e-book format.

I have no interest in replicating the Previewer's capabilities but I do see how having an alternative to using it could be useful to others. This plugin seems like a good idea to me.

[kovidgoyal]

Originally Posted by jloutsch

My opinion was that KFX can display any custom fonts installed on the kindle, which would negate the need to embed fonts?

That would imply that every book is limited to the fonts ont he kindle. Embedded have many use cases, such as showing glyphs from other writing systems, showing stylised text such as handwriting fonts, showing special symbols such as mathematical fonts etc etc