{"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":"python","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,"search_vec":"'2':18 '2.5.1':56 'access':28 'activ':61 'advanc':35 'applic':26 'bind':3,14,73 'bundl':40 'cadenc':63 'common':45 'content':30 'current':53 'enabl':25 'engin':23 'experi':51 'font':22,29,67 'freetyp':1,4,7,17,41,69 'freetype-pi':6 'glyph':32 'graphic':70 'harfbuzz':43 'high':11 'high-level':10 'instal':50 'level':12 'librari':19,39 'maintain':59 'offer':47 'oper':37 'perform':34 'platform':46 'provid':9 'py':8 'python':2,5,13 'regular':65 'releas':62 'render':31,68 'softwar':21 'straightforward':49 'text':71 'typograph':36 'typographi':72 'updat':66 'version':54","created_at":"2026-04-09T18:40:49.206979+00:00","updated_at":"2026-04-16T15:11:14.053571+00:00","problems":[{"fix":"Ensure `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`).","cause":"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.","error":"RuntimeError: Freetype library not found"},{"fix":"Install `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.","cause":"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.","error":"OSError: [WinError 126] The specified module could not be found"},{"fix":"Verify 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.","cause":"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.","error":"freetype.ft_errors.FT_Exception: FT_Exception: (cannot open resource)"},{"fix":"Install 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`.","cause":"The `freetype-py` package is not installed in the active Python environment, or the import statement is incorrect.","error":"ModuleNotFoundError: No module named 'freetype'"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"2.5.1","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/rougier/freetype-py","docs":null,"changelog":null,"pypi":"https://pypi.org/project/freetype-py/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["serialization"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-06-28","next_check":"2026-07-28","install_tag":null}}