---
id: uharfbuzz
version: "0.56.0"
license: Apache License 2.0
license_treatment: permissive
maintenance: active
---

# uharfbuzz — Streamlined Cython bindings for the harfbuzz shaping engine

License: permissive · Maintenance: active · Downloads: 960.3K/mo

## What it is and what it does

uharfbuzz is a Python wrapper around the HarfBuzz text shaping engine, a C library that converts Unicode text and font files into positioned glyphs. It handles complex typography tasks like kerning (adjusting spacing between letter pairs), ligature substitution (combining characters like 'fi' into a single glyph), and script-specific shaping rules. The package bundles minimal HarfBuzz sources by default, so installation requires no separate system dependency—though you can opt into using a system-provided HarfBuzz build if needed.

You load a font file, create a buffer with text, apply shaping with optional features, then iterate over the resulting glyph infos and positions to extract advance widths, offsets, and glyph IDs. It's a thin, direct binding to HarfBuzz's core API, exposing the shaping pipeline without abstraction layers. The package is actively maintained, supports current Python versions (3.10+), and offers prebuilt wheels for major platforms.

Use it for:

- Render text to screen or image with proper kerning and ligatures in graphics or game engines.
- Build font inspection tools that need to map characters to glyphs and measure their positions.
- Implement complex script support (Arabic, Devanagari, etc.) where character-to-glyph mapping is non-trivial.
- Generate PDF or vector output with correct text layout and glyph positioning.
- Validate font behavior by programmatically shaping test strings and inspecting glyph metrics.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Cython bindings for HarfBuzz that shape text using font files, converting character strings into positioned glyphs with kerning and ligature support.

Yes. The package is actively maintained, has no known vulnerabilities, offers permissive licensing, and provides prebuilt wheels for common platforms. Install friction is moderate but manageable. Choose it if you need direct, low-level control over text shaping and glyph positioning; it's the standard Python binding for HarfBuzz.

## Install

pip install uharfbuzz
uv add uharfbuzz
poetry add uharfbuzz

## Installing uharfbuzz

Before you install: Medium install friction due to compiled C extensions. Prebuilt wheels available for common platforms (CPython 3.10+, PyPy 3.11) and architectures. Alternatively, can build against system HarfBuzz via USE_SYSTEM_LIBS=1 if pkg-config is available. Package is actively maintained with recent releases.

License in practice: Apache License 2.0 is permissive; you may use, modify, and distribute this package freely in commercial or private projects provided you include the license notice.

Quickstart:

import uharfbuzz as hb

blob = hb.Blob.from_file_path('font.ttf')
face = hb.Face(blob)
font = hb.Font(face)
buf = hb.Buffer()
buf.add_str('Hello')
buf.guess_segment_properties()
hb.shape(font, buf, {"kern": True})
for info, pos in zip(buf.glyph_infos, buf.glyph_positions):
    print(f"glyph {info.codepoint}: x_advance={pos.x_advance}")

Requires Python 3.10 or later. If building from source against system HarfBuzz, pkg-config and HarfBuzz development headers must be available.

Verify before relying:

- Whether prebuilt wheels cover all deployment targets you need beyond the listed platforms (macOS, Linux, Windows, WebAssembly).
- Performance characteristics when shaping large volumes of text or complex scripts.

## Package facts

- License: Apache License 2.0 (permissive)
- Python support: supports_current
- Install friction: medium
- Maintenance: active
- Downloads: 960.3K/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

text shaping harfbuzz, font glyph positioning, text rendering with fonts, harfbuzz python bindings, kerning ligature shaping, font layout engine, unicode text layout, text-shaping, typography, font-rendering

[View on SkillFed](https://skillfed.io/packages/uharfbuzz) · [View on PyPI](https://pypi.org/project/uharfbuzz/)