{"id":2037,"library":"freetype-py","title":"Freetype Python Bindings","description":"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.","status":"active","version":"2.5.1","language":"en","source_language":"en","source_url":"https://github.com/rougier/freetype-py","tags":["font","rendering","freetype","graphics","text","typography","bindings"],"install":[{"cmd":"pip install freetype-py","lang":"bash","label":"Recommended (with bundled FreeType)"},{"cmd":"export FREETYPEPY_BUNDLE_FT=yesplease && pip install freetype-py","lang":"bash","label":"Compile FreeType from source (requires build tools)"},{"cmd":"pip install --no-binary freetype-py freetype-py","lang":"bash","label":"Install with external FreeType library"}],"dependencies":[{"reason":"Core font rendering engine; often bundled with `freetype-py` wheels, but required as a system library if `--no-binary` is used or on unsupported architectures.","package":"FreeType 2 (C library)","optional":false},{"reason":"Text shaping engine; often bundled with `freetype-py` wheels for advanced text layout features.","package":"HarfBuzz (C library)","optional":true},{"reason":"Required for compiling FreeType from source, particularly on Windows, macOS, and Linux if `FREETYPEPY_BUNDLE_FT=1` is set or `--no-binary` is used.","package":"CMake","optional":true},{"reason":"Required for compiling FreeType from source on Linux, macOS, or Windows if bundling or linking externally.","package":"C/C++ compiler (e.g., gcc/g++, Visual C++)","optional":true}],"imports":[{"note":"The primary module for accessing FreeType functionalities.","symbol":"freetype","correct":"import freetype"},{"note":"Direct import from `freetype.raw` is discouraged as it exposes low-level C API bindings, while `freetype` module provides the high-level API.","wrong":"from freetype.raw import Face","symbol":"Face","correct":"import freetype\nface = freetype.Face(\"font.ttf\")"}],"quickstart":{"code":"import freetype\nimport os\n\n# Ensure a font file is available for the example\n# In a real application, you'd use a path to an existing font.\nfont_path = os.environ.get('FREETYPE_FONT_PATH', 'Vera.ttf') # Replace with actual font path or ensure Vera.ttf is present\n\ntry:\n    face = freetype.Face(font_path)\n    face.set_char_size(48 * 64) # 48 points, 64-bit fractional font sizes\n    face.load_char('S')\n\n    # Access the glyph bitmap\n    bitmap = face.glyph.bitmap\n\n    # Print a simple representation of the bitmap buffer\n    if bitmap.width > 0 and bitmap.rows > 0:\n        print(f\"Loaded character 'S' from {font_path}\")\n        print(f\"Bitmap dimensions: {bitmap.width}x{bitmap.rows}\")\n        # Example of printing the first few bytes of the buffer\n        print(\"Bitmap buffer start:\", list(bitmap.buffer[:min(10, len(bitmap.buffer))]))\n    else:\n        print(f\"Character 'S' has no bitmap data from {font_path}\")\n\nexcept freetype.ft_errors.FT_Exception as e:\n    print(f\"Freetype error: {e}. Make sure '{font_path}' is a valid font file.\")\nexcept FileNotFoundError:\n    print(f\"Error: Font file '{font_path}' not found. Please provide a valid font file.\")\nexcept Exception as e:\n    print(f\"An unexpected error occurred: {e}\")","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade your Python environment to Python 3 (>=3.7 as per PyPI) and ensure you are using a 64-bit Python interpreter.","message":"As of v2.2.0, `freetype-py` has dropped official support for Python 2 and 32-bit wheel distributions.","severity":"breaking","affected_versions":"< 2.2.0"},{"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.","message":"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.","severity":"breaking","affected_versions":"< 2.1.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions, when compiling from source."}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}