Freetype Python Bindings

2.5.1 · active · verified Thu Apr 09

Freetype Python (`freetype-py`) provides high-level Python bindings for the FreeType 2 library, a software font engine. It enables applications to access font contents, render glyphs, and perform advanced typographic operations. The library bundles FreeType and HarfBuzz for common platforms, offering a straightforward installation experience. The current version is 2.5.1, and it maintains an active release cadence with regular updates.

Warnings

breaking As of v2.2.0, `freetype-py` has dropped official support for Python 2 and 32-bit wheel distributions.
Fix: Upgrade your Python environment to Python 3 (>=3.7 as per PyPI) and ensure you are using a 64-bit Python interpreter.
breaking The internal FreeType functions `FT_Outline_New_Internal` and `FT_Outline_Done_Internal` were removed from `freetype-py`'s exposed API as of v2.1.0, as they were accidentally made public.
Fix: Review your code for direct calls to these functions. For outline decomposition, consider using `Outline.decompose()` or other high-level API alternatives for outline manipulation. Refer to FreeType's C API documentation for equivalent public functions if direct low-level access is required.
gotcha While `pip install freetype-py` typically bundles the FreeType C library for common platforms (Windows, macOS, Linux x86/x64), custom installation scenarios (e.g., `--no-binary`, unsupported architectures, or `FREETYPEPY_BUNDLE_FT=1`) require a system-wide FreeType 2 C library and potentially build tools (CMake, C/C++ compiler) to be present.
Fix: For `--no-binary` installs, ensure FreeType 2 is installed on your system (e.g., `apt-get install libfreetype-dev` on Debian/Ubuntu, `brew install freetype` on macOS). On Windows, `freetype.dll` must be in a system `PATH` and match your Python's architecture. For custom builds, ensure CMake and a compatible C/C++ compiler are installed.
gotcha The `pygame.freetype` module is part of the `pygame` library and provides separate FreeType 2 bindings, independent of `freetype-py`. If you are working specifically with Pygame, `pygame.freetype` is the module to use.
Fix: If your goal is Pygame integration, use `import pygame.freetype` and consult the Pygame documentation. `freetype-py` is a general-purpose binding for FreeType, not specific to Pygame's rendering pipeline.
gotcha When compiling FreeType from source (e.g., by setting `FREETYPEPY_BUNDLE_FT=1`), the compilation process downloads and builds FreeType and HarfBuzz. Ensure your environment has the necessary build tools (CMake, C/C++ compiler, specific multilib packages for cross-compilation on Linux) and sufficient permissions.
Fix: Consult the `freetype-py` installation documentation on GitHub or PyPI for detailed requirements specific to your operating system and desired architecture before attempting to compile from source.

Install

pip install freetype-py Recommended (with bundled FreeType)
export FREETYPEPY_BUNDLE_FT=yesplease && pip install freetype-py Compile FreeType from source (requires build tools)
pip install --no-binary freetype-py freetype-py Install with external FreeType library

Imports

freetype
```
import freetype
```
The primary module for accessing FreeType functionalities.
Face
```
import freetype
face = freetype.Face("font.ttf")
```
Direct import from `freetype.raw` is discouraged as it exposes low-level C API bindings, while `freetype` module provides the high-level API.

Quickstart

This example demonstrates how to load a font, set its size, load a character's glyph, and access its bitmap data using the high-level `freetype-py` API.

import freetype
import os

# Ensure a font file is available for the example
# In a real application, you'd use a path to an existing font.
font_path = os.environ.get('FREETYPE_FONT_PATH', 'Vera.ttf') # Replace with actual font path or ensure Vera.ttf is present

try:
    face = freetype.Face(font_path)
    face.set_char_size(48 * 64) # 48 points, 64-bit fractional font sizes
    face.load_char('S')

    # Access the glyph bitmap
    bitmap = face.glyph.bitmap

    # Print a simple representation of the bitmap buffer
    if bitmap.width > 0 and bitmap.rows > 0:
        print(f"Loaded character 'S' from {font_path}")
        print(f"Bitmap dimensions: {bitmap.width}x{bitmap.rows}")
        # Example of printing the first few bytes of the buffer
        print("Bitmap buffer start:", list(bitmap.buffer[:min(10, len(bitmap.buffer))]))
    else:
        print(f"Character 'S' has no bitmap data from {font_path}")

except freetype.ft_errors.FT_Exception as e:
    print(f"Freetype error: {e}. Make sure '{font_path}' is a valid font file.")
except FileNotFoundError:
    print(f"Error: Font file '{font_path}' not found. Please provide a valid font file.")
except Exception as e:
    print(f"An unexpected error occurred: {e}")

view raw JSON →