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.
Install & Compatibility
Where this runs
tested against v2.5.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
py 3.10
9/10 runs
9/10 runs
py 3.11
9/10 runs
9/10 runs
py 3.12
9/10 runs
9/10 runs
py 3.13
9/10 runs
9/10 runs
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
freetype
✓ import freetype
The primary module for accessing FreeType functionalities.
Face
✓ import freetype
face = freetype.Face("font.ttf")
✗ from freetype.raw import Face
Direct import from `freetype.raw` is discouraged as it exposes low-level C API bindings, while `freetype` module provides the high-level API.
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}")
Debug
Known issues
breakingAs of v2.2.0, `freetype-py` has dropped official support for Python 2 and 32-bit wheel distributions.fixUpgrade your Python environment to Python 3 (>=3.7 as per PyPI) and ensure you are using a 64-bit Python interpreter.
affects: < 2.2.0
breakingThe 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.fixReview 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.
affects: < 2.1.0
gotchaWhile `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.fixFor `--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.
affects: All versions
gotchaThe `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.fixIf 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.
affects: All versions
gotchaWhen 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.fixConsult 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.
affects: All versions, when compiling from source.
Errors
Common errors & fixes
RuntimeError: Freetype library not found
The `freetype-py` library cannot locate the underlying FreeType 2 DLL/shared library on the system, often due to a failed bundled binary installation or a missing system-wide FreeType installation.
fixEnsure `freetype-py` is installed using `pip install freetype-py`. On Windows, if this fails, manually download 'freetype.dll' (matching your Python's architecture) and place it in your system's PATH or directly in the `site-packages/freetype` directory. For Linux/macOS, install FreeType 2 development libraries via your package manager (e.g., `sudo apt-get install libfreetype6-dev` or `brew install freetype`).
OSError: [WinError 126] The specified module could not be found
This Windows-specific error indicates that `freetype-py` could not find the `freetype.dll` file required to load the underlying FreeType library, similar to the 'Freetype library not found' runtime error.
fixInstall `freetype-py` using `pip install freetype-py`. If the error persists, manually download the correct 'freetype.dll' (32-bit or 64-bit to match your Python installation) and place it in a directory listed in your system's PATH environment variable, or directly into the `freetype` folder within your Python `site-packages` directory.
freetype.ft_errors.FT_Exception: FT_Exception: (cannot open resource)
The font file specified in `freetype.Face()` either does not exist at the provided path, the path is incorrect, or the file is corrupted/unreadable.
fixVerify that the font file (e.g., '.ttf', '.otf') exists at the exact path provided to `freetype.Face()`. Use an absolute file path, or ensure the font file is in your current working directory or another location accessible by your application.
ModuleNotFoundError: No module named 'freetype'
The `freetype-py` package is not installed in the active Python environment, or the import statement is incorrect.
fixInstall the library using `pip install freetype-py`. Ensure your Python environment is activated if using a virtual environment, and use the correct import statement: `import freetype`.
Audit
Dependencies
FreeType 2 (C library)requiredCore font rendering engine; often bundled with `freetype-py` wheels, but required as a system library if `--no-binary` is used or on unsupported architectures.
HarfBuzz (C library)optionalText shaping engine; often bundled with `freetype-py` wheels for advanced text layout features.
CMakeoptionalRequired for compiling FreeType from source, particularly on Windows, macOS, and Linux if `FREETYPEPY_BUNDLE_FT=1` is set or `--no-binary` is used.
C/C++ compiler (e.g., gcc/g++, Visual C++)optionalRequired for compiling FreeType from source on Linux, macOS, or Windows if bundling or linking externally.