HarfBuzz: the text shaping engine that most screens already run

What HarfBuzz solves, and who ends up depending on it

A font file does not contain letters. It contains glyph outlines plus tables that describe how those glyphs should be chosen and placed for a given sequence of characters. Turning the string a user typed into the glyphs and positions a rasterizer can draw is a separate job, and it is the job HarfBuzz does. The README calls it a text shaping engine that has grown into a full font platform, and the description it reaches for is "the ffmpeg of text shaping".

The people who need it are not usually writing a text editor. They are writing a browser engine, a PDF generator, an ebook reader, a game UI, or a terminal that has to render Devanagari, Arabic or a variable font correctly. The README claims HarfBuzz shapes the majority of text on modern screens, which is consistent with how deeply it is embedded: it is the shaping layer under many toolkits rather than an application users launch.

The design priority is stated plainly: robustness, correctness, performance, in that order. That ordering explains a lot of the project's decisions. A malformed font should not take down the process, so the code is defensive even where that costs speed. If you are choosing a shaping library for a hostile input path, such as a service that renders user-supplied fonts, that priority is the reason to look here first.

How the shaping pipeline is put together

The core library is libharfbuzz, and it covers text shaping plus the draw and paint APIs. Around it sit optional integration backends compiled in at build time: hb-ft for FreeType, hb-coretext on macOS, hb-uniscribe, hb-directwrite and hb-gdi on Windows, plus hb-glib and hb-graphite2. These are the seams where HarfBuzz meets a platform's font loading or rendering. Choosing a backend is a build decision, not a runtime one.

The README describes two font technologies as first-class: OpenType primarily, and Apple Advanced Typography as well. That combination is unusual. A shaper that handles AAT natively can process fonts that OpenType-only engines treat as opaque, and the README links a 2020 study titled HarfBuzz OT+AAT "Unishaper" about exactly that convergence.

A second library, libharfbuzz-subset, handles font subsetting and variable-font instancing. This is the part that produces a smaller font rather than positioned glyphs, and it is exposed through the hb-subset command-line tool. Keeping it in the same repository means the shaping code and the subsetting code share the same font parsing, which is a meaningful reduction in surface area for anyone doing both.

Three libraries are labeled experimental: libharfbuzz-raster for glyph rasterization to bitmaps including color fonts, libharfbuzz-vector for vector output currently limited to SVG, and libharfbuzz-gpu, which encodes glyph outlines for GPU rasterization using the Slug algorithm and ships shader sources in GLSL, WGSL, MSL and HLSL. Treat the experimental label as a schedule statement, not a warning. The APIs are usable, but the README does not promise the stability that hb.h gets.

The hb-shape tool and the rest of the command line

The README points to the GitHub releases page for tarball releases and Win32/Win64 binary bundles, and to BUILD.md for build information. Distribution packages are tracked through the packaging badge, so on Linux the usual route is your distribution's package for the library and its utilities. The command-line tools in the README are hb-shape, hb-view, hb-subset, hb-info, hb-raster, hb-vector and hb-gpu.

Once the tools are installed, hb-shape is the fastest way to see what shaping actually does. The README describes it as shaping text and displaying glyph output. Running it against a font file and a string gives a list of glyph IDs with positions rather than readable text, and that is the point: you are looking at what the rasterizer would receive. If the font has ligatures or contextual forms, the glyph count will not match the character count, and that difference is the shaping engine working.

For a quick look at the result as an image rather than glyph IDs, hb-view is described in the README as rendering shaped text to an image.

If you are working from Python, the README points to README.python.md and to a separate project, uharfbuzz. The repository also ships amalgamated sources for simplified builds: harfbuzz.cc for just libharfbuzz, harfbuzz-subset.cc for just libharfbuzz-subset, and harfbuzz-world.cc for everything, driven by a custom hb-features.h. For a worked example of the world.cc single-file build, the README points to harfbuzz-world.cc, which is also an interactive playground for shaping, subsetting, rasterization, vector output and GPU rendering in the browser.

Where HarfBuzz stops: no hinting, and a rasterizer still needed

The README names one notable missing feature directly: font hinting, including autohinting, is not implemented. For hinted rasterization it points elsewhere, to FreeType or Skrifa. This is the single most important boundary to understand before adopting HarfBuzz. Shaping produces glyph IDs and positions; it does not produce pixels. If your target is a small screen where grid-fitting matters, or an environment where hinted output is a requirement, HarfBuzz is one part of the stack and not the whole of it.

The experimental libraries narrow that gap but do not close it. libharfbuzz-raster rasterizes glyphs to bitmaps and handles color fonts, and libharfbuzz-gpu encodes outlines for GPU rasterization. Neither is described as implementing hinting. So the split remains: HarfBuzz decides which glyph and where, something else decides what the glyph looks like at a given size.

There is a second boundary in the build itself. The integration backends are compiled in, which means a HarfBuzz built for one platform does not automatically carry the behavior of another. A binary without hb-coretext behaves differently on macOS from one without hb-ft on Linux, and the README does not present these as interchangeable. If you ship prebuilt binaries, you are shipping a set of choices.

Finally, the README does not document rollback or downgrade procedures, and it does not describe a migration path if a future release did break something. The API stability promise covers the API and ABI, not the behavior of a specific shaping result. Two releases can shape the same string differently while remaining binary compatible.

HarfBuzz versus FreeType, and versus a full text stack

The comparison people search for is HarfBuzz against FreeType, and the honest answer is that they are not substitutes. FreeType is a font rasterizer. It loads a font and produces bitmaps or outlines, and it implements hinting. HarfBuzz is a shaper. It takes a string and a font and produces glyph IDs and positions. The README's own advice for hinted rasterization is to use FreeType or Skrifa alongside HarfBuzz, which tells you the intended relationship is adjacency, not replacement.

That adjacency is why hb-ft exists as a compiled-in backend. When HarfBuzz is built with FreeType integration, the two libraries cooperate rather than compete. A project that already uses FreeType for rasterization and adds HarfBuzz for shaping is following the path the README describes, not working around it.

Against a full text stack such as Pango, the difference is scope. Pango handles line breaking, bidirectional text, font fallback and the higher-level layout questions, and it uses a shaper underneath. HarfBuzz deliberately does not do line breaking or fallback. It shapes the run you give it. If you want a complete layout solution, HarfBuzz is a component of one. If you want to control layout yourself and only outsource the shaping, HarfBuzz is the layer you want, and pulling in a full stack would give you a second opinion about line breaking that you did not ask for.

Licence, versioning and the cost of upgrading

The repository metadata reports the licence as NOASSERTION, and the README says only that license information is in COPYING. That is a gap worth closing yourself before you ship. Read COPYING and have whoever handles licensing at your organization confirm the terms for your use, because the metadata alone does not name a licence and this article cannot tell you what it says.

Upgrade cost is unusually low for a library of this size, and the README explains why. The API that comes with hb.h will not change incompatibly, and the project states it will never break the ABI. The README goes further: the API and ABI are stable even across major version number jumps, and current HarfBuzz is API/ABI compatible back to the 0.9.x series. Major versions are bumped for major new features, minor versions for new API, and micro versions for bug fixes. That means a distro shipping an older HarfBuzz will not fail to link against code written for a newer one.

Peripheral headers are a different matter. The README says they are more likely to go through minor modifications, though the project still tries not to change API incompatibly. If you depend on anything outside hb.h, pin your version and read the release notes. The release cadence visible in the repository is brisk, with 14.5.0, 14.4.0 and 14.3.1 all published within roughly six weeks, so there is no shortage of changelog to read. The last push was on 2026-09-21.

Editorial conclusion

Adopt HarfBuzz if you render text and need correct OpenType or AAT shaping: browsers, layout engines, PDF and ebook pipelines, and anything that mixes scripts, ligatures or variable fonts. Do not adopt it expecting a renderer. Font hinting and autohinting are not implemented, and the README points to FreeType or Skrifa for hinted rasterization, so a rasterizer still has to sit next to it. Before committing, verify the licence terms in COPYING, since the repository metadata reports NOASSERTION rather than a named licence, and confirm that your target platform is covered by one of the integration backends listed in the README. The API contract is the strongest reason to build on it: the README states that the API and ABI are stable even across major version jumps and compatible back to the 0.9.x series.

Frequently asked questions

Official sources

1. harfbuzz/harfbuzz on GitHub
2. Issues
3. Project website
4. README
5. Releases