# `ImageFont` Module

The `ImageFont` module defines a class with the same name. Instances of this class store bitmap fonts, and are used with the `PIL.ImageDraw.ImageDraw.text()` method.

PIL uses its own font file format to store bitmap fonts, limited to 256 characters. You can use pilfont.py from pillow-scripts to convert BDF and PCF font descriptors (X window font formats) to this format.

Starting with version 1.1.4, PIL can be configured to support TrueType and OpenType fonts (as well as other font formats supported by the FreeType library). For earlier versions, TrueType support is only available as part of the imToolkit package.

Warning

To protect against potential DOS attacks when using arbitrary strings as text input, Pillow will raise a `ValueError` if the number of characters is over a certain limit, `MAX_STRING_LENGTH`.

This threshold can be changed by setting `MAX_STRING_LENGTH`. It can be disabled by setting `ImageFont.MAX_STRING_LENGTH = None`.

## Example

    from PIL import ImageFont, ImageDraw

    draw = ImageDraw.Draw(image)

    # use a bitmap font
    font = ImageFont.load("arial.pil")

    draw.text((10, 10), "hello", font=font)

    # use a truetype font
    font = ImageFont.truetype("arial.ttf", 15)

    draw.text((10, 25), "world", font=font)

## Functions

PIL.ImageFont.load(filename)

  Load a font file. This function loads a font object from the given bitmap font file, and returns the corresponding font object.

  Parameters

    filename – Name of font file.

  Returns

    A font object.

  Raises

    OSError – If the file could not be read.

PIL.ImageFont.load_path(filename)

  Load font file. Same as `load()`, but searches for a bitmap font along the Python path.

  Parameters

    filename – Name of font file.

  Returns

    A font object.

  Raises

    OSError – If the file could not be read.

PIL.ImageFont.truetype(font=None, size=10, index=0, encoding='', layout_engine=None)

  Load a TrueType or OpenType font from a file or file-like object, and create a font object. This function loads a font object from the given file or file-like object, and creates a font object for a font of the given size.

  Pillow uses FreeType to open font files. If you are opening many fonts simultaneously on Windows, be aware that Windows limits the number of files that can be open in C at once to 512. If you approach that limit, an `OSError` may be thrown, reporting that FreeType “cannot open resource”.

  This function requires the _imagingft service.

  Parameters

    - font – A filename or file-like object containing a TrueType font. If the file is not found in this filename, the loader may also search in other directories, such as the `fonts/` directory on Windows or `/Library/Fonts/`, `/System/Library/Fonts/` and `~/Library/Fonts/` on macOS.

    - size – The requested size, in points.

    - index – Which font face to load (default is first available face).

    - encoding –

      Which font encoding to use (default is Unicode). Possible encodings include (see the FreeType documentation for more information):

      - ”unic” (Unicode)

      - ”symb” (Microsoft Symbol)

      - ”ADOB” (Adobe Standard)

      - ”ADBE” (Adobe Expert)

      - ”ADBC” (Adobe Custom)

      - ”armn” (Apple Roman)

      - ”sjis” (Shift JIS)

      - ”gb ” (PRC)

      - ”big5”

      - ”wans” (Extended Wansung)

      - ”joha” (Johab)

      - ”lat1” (Latin-1)

      This specifies the character set to use. It does not alter the encoding of any text provided in subsequent operations.

    - layout_engine –

      Which layout engine to use, if available: `ImageFont.LAYOUT_BASIC` or `ImageFont.LAYOUT_RAQM`.

      You can check support for Raqm layout using `PIL.features.check_feature()` with `feature="raqm"`.

      New in version 4.2.0.

  Returns

    A font object.

  Raises

    OSError – If the file could not be read.

PIL.ImageFont.load_default()

  Load a “better than nothing” default font.

  New in version 1.1.4.

  Returns

    A font object.

## Methods

class PIL.ImageFont.ImageFont

  PIL font wrapper

  getmask(text, mode='', *args, **kwargs)

    Create a bitmap for the text.

    If the font uses antialiasing, the bitmap should have mode `L` and use a maximum value of 255. Otherwise, it should have mode `1`.

    Parameters

      - text – Text to render.

      - mode –

        Used by some graphics drivers to indicate what mode the driver prefers; if empty, the renderer may return either mode. Note that the mode is always a string, to simplify C-level implementations.

        New in version 1.1.5.

    Returns

      An internal PIL storage memory instance as defined by the `PIL.Image.core` interface module.

  getsize(text, *args, **kwargs)

    Returns width and height (in pixels) of given text.

    Parameters

      text – Text to measure.

    Returns

      (width, height)

class PIL.ImageFont.FreeTypeFont(font=None, size=10, index=0, encoding='', layout_engine=None)

  FreeType font wrapper (requires _imagingft service)

  font_variant(font=None, size=None, index=None, encoding=None, layout_engine=None)

    Create a copy of this FreeTypeFont object, using any specified arguments to override the settings.

    Parameters are identical to the parameters used to initialize this object.

    Returns

      A FreeTypeFont object.

  get_variation_axes()
    Returns

      A list of the axes in a variation font.

    Raises

      OSError – If the font is not a variation font.

  get_variation_names()
    Returns

      A list of the named styles in a variation font.

    Raises

      OSError – If the font is not a variation font.

  getbbox(text, mode='', direction=None, features=None, language=None, stroke_width=0, anchor=None)

    Returns bounding box (in pixels) of given text relative to given anchor when rendered in font with provided direction, features, and language.

    Use `getlength()` to get the offset of following text with 1/64 pixel precision. The bounding box includes extra margins for some fonts, e.g. italics or accents.

    New in version 8.0.0.

    Parameters

      - text – Text to render.

      - mode – Used by some graphics drivers to indicate what mode the driver prefers; if empty, the renderer may return either mode. Note that the mode is always a string, to simplify C-level implementations.

      - direction – Direction of the text. It can be ‘rtl’ (right to left), ‘ltr’ (left to right) or ‘ttb’ (top to bottom). Requires libraqm.

      - features – A list of OpenType font features to be used during text layout. This is usually used to turn on optional font features that are not enabled by default, for example ‘dlig’ or ‘ss01’, but can be also used to turn off default font features for example ‘-liga’ to disable ligatures or ‘-kern’ to disable kerning. To get all supported features, see https://docs.microsoft.com/en-us/typography/opentype/spec/featurelist Requires libraqm.

      - language – Language of the text. Different languages may use different glyph shapes or ligatures. This parameter tells the font which language the text is in, and to apply the correct substitutions as appropriate, if available. It should be a BCP 47 language code Requires libraqm.

      - stroke_width – The width of the text stroke.

      - anchor – The text anchor alignment. Determines the relative location of the anchor to the text. The default alignment is top left. See Text anchors for valid values.

    Returns

      `(left, top, right, bottom)` bounding box

  getlength(text, mode='', direction=None, features=None, language=None)

    Returns length (in pixels with 1/64 precision) of given text when rendered in font with provided direction, features, and language.

    This is the amount by which following text should be offset. Text bounding box may extend past the length in some fonts, e.g. when using italics or accents.

    The result is returned as a float; it is a whole number if using basic layout.

    Note that the sum of two lengths may not equal the length of a concatenated string due to kerning. If you need to adjust for kerning, include the following character and subtract its length.

    For example, instead of

        hello = font.getlength("Hello")
        world = font.getlength("World")
        hello_world = hello + world  # not adjusted for kerning
        assert hello_world == font.getlength("HelloWorld")  # may fail

    use

        hello = font.getlength("HelloW") - font.getlength("W")  # adjusted for kerning
        world = font.getlength("World")
        hello_world = hello + world  # adjusted for kerning
        assert hello_world == font.getlength("HelloWorld")  # True

    or disable kerning with (requires libraqm)

        hello = draw.textlength("Hello", font, features=["-kern"])
        world = draw.textlength("World", font, features=["-kern"])
        hello_world = hello + world  # kerning is disabled, no need to adjust
        assert hello_world == draw.textlength("HelloWorld", font, features=["-kern"])

    New in version 8.0.0.

    Parameters

      - text – Text to measure.

      - mode – Used by some graphics drivers to indicate what mode the driver prefers; if empty, the renderer may return either mode. Note that the mode is always a string, to simplify C-level implementations.

      - direction – Direction of the text. It can be ‘rtl’ (right to left), ‘ltr’ (left to right) or ‘ttb’ (top to bottom). Requires libraqm.

      - features – A list of OpenType font features to be used during text layout. This is usually used to turn on optional font features that are not enabled by default, for example ‘dlig’ or ‘ss01’, but can be also used to turn off default font features for example ‘-liga’ to disable ligatures or ‘-kern’ to disable kerning. To get all supported features, see https://docs.microsoft.com/en-us/typography/opentype/spec/featurelist Requires libraqm.

      - language –

        Language of the text. Different languages may use different glyph shapes or ligatures. This parameter tells the font which language the text is in, and to apply the correct substitutions as appropriate, if available. It should be a BCP 47 language code Requires libraqm.

    Returns

      Width for horizontal, height for vertical text.

  getmask(text, mode='', direction=None, features=None, language=None, stroke_width=0, anchor=None, ink=0)

    Create a bitmap for the text.

    If the font uses antialiasing, the bitmap should have mode `L` and use a maximum value of 255. If the font has embedded color data, the bitmap should have mode `RGBA`. Otherwise, it should have mode `1`.

    Parameters

      - text – Text to render.

      - mode –

        Used by some graphics drivers to indicate what mode the driver prefers; if empty, the renderer may return either mode. Note that the mode is always a string, to simplify C-level implementations.

        New in version 1.1.5.

      - direction –

        Direction of the text. It can be ‘rtl’ (right to left), ‘ltr’ (left to right) or ‘ttb’ (top to bottom). Requires libraqm.

        New in version 4.2.0.

      - features –

        A list of OpenType font features to be used during text layout. This is usually used to turn on optional font features that are not enabled by default, for example ‘dlig’ or ‘ss01’, but can be also used to turn off default font features for example ‘-liga’ to disable ligatures or ‘-kern’ to disable kerning. To get all supported features, see https://docs.microsoft.com/en-us/typography/opentype/spec/featurelist Requires libraqm.

        New in version 4.2.0.

      - language –

        Language of the text. Different languages may use different glyph shapes or ligatures. This parameter tells the font which language the text is in, and to apply the correct substitutions as appropriate, if available. It should be a BCP 47 language code Requires libraqm.

        New in version 6.0.0.

      - stroke_width –

        The width of the text stroke.

        New in version 6.2.0.

      - anchor –

        The text anchor alignment. Determines the relative location of the anchor to the text. The default alignment is top left. See Text anchors for valid values.

        > New in version 8.0.0.

      - ink –

        Foreground ink for rendering in RGBA mode.

        New in version 8.0.0.

    Returns

      An internal PIL storage memory instance as defined by the `PIL.Image.core` interface module.

  getmask2(text, mode='', fill=<built-in function fill>, direction=None, features=None, language=None, stroke_width=0, anchor=None, ink=0, *args, **kwargs)

    Create a bitmap for the text.

    If the font uses antialiasing, the bitmap should have mode `L` and use a maximum value of 255. If the font has embedded color data, the bitmap should have mode `RGBA`. Otherwise, it should have mode `1`.

    Parameters

      - text – Text to render.

      - mode –

        Used by some graphics drivers to indicate what mode the driver prefers; if empty, the renderer may return either mode. Note that the mode is always a string, to simplify C-level implementations.

        New in version 1.1.5.

      - direction –

        Direction of the text. It can be ‘rtl’ (right to left), ‘ltr’ (left to right) or ‘ttb’ (top to bottom). Requires libraqm.

        New in version 4.2.0.

      - features –

        A list of OpenType font features to be used during text layout. This is usually used to turn on optional font features that are not enabled by default, for example ‘dlig’ or ‘ss01’, but can be also used to turn off default font features for example ‘-liga’ to disable ligatures or ‘-kern’ to disable kerning. To get all supported features, see https://docs.microsoft.com/en-us/typography/opentype/spec/featurelist Requires libraqm.

        New in version 4.2.0.

      - language –

        Language of the text. Different languages may use different glyph shapes or ligatures. This parameter tells the font which language the text is in, and to apply the correct substitutions as appropriate, if available. It should be a BCP 47 language code Requires libraqm.

        New in version 6.0.0.

      - stroke_width –

        The width of the text stroke.

        New in version 6.2.0.

      - anchor –

        The text anchor alignment. Determines the relative location of the anchor to the text. The default alignment is top left. See Text anchors for valid values.

        > New in version 8.0.0.

      - ink –

        Foreground ink for rendering in RGBA mode.

        New in version 8.0.0.

    Returns

      A tuple of an internal PIL storage memory instance as defined by the `PIL.Image.core` interface module, and the text offset, the gap between the starting coordinate and the first marking

  getmetrics()
    Returns

      A tuple of the font ascent (the distance from the baseline to the highest outline point) and descent (the distance from the baseline to the lowest outline point, a negative value)

  getname()
    Returns

      A tuple of the font family (e.g. Helvetica) and the font style (e.g. Bold)

  getoffset(text)

    Returns the offset of given text. This is the gap between the starting coordinate and the first marking. Note that this gap is included in the result of `getsize()`.

    Parameters

      text – Text to measure.

    Returns

      A tuple of the x and y offset

  getsize(text, direction=None, features=None, language=None, stroke_width=0)

    Returns width and height (in pixels) of given text if rendered in font with provided direction, features, and language.

    Use `getlength()` to measure the offset of following text with 1/64 pixel precision. Use `getbbox()` to get the exact bounding box based on an anchor.

    Note

    For historical reasons this function measures text height from the ascender line instead of the top, see Text anchors. If you wish to measure text height from the top, it is recommended to use the bottom value of `getbbox()` with `anchor='lt'` instead.

    Parameters

      - text – Text to measure.

      - direction –

        Direction of the text. It can be ‘rtl’ (right to left), ‘ltr’ (left to right) or ‘ttb’ (top to bottom). Requires libraqm.

        New in version 4.2.0.

      - features –

        A list of OpenType font features to be used during text layout. This is usually used to turn on optional font features that are not enabled by default, for example ‘dlig’ or ‘ss01’, but can be also used to turn off default font features for example ‘-liga’ to disable ligatures or ‘-kern’ to disable kerning. To get all supported features, see https://docs.microsoft.com/en-us/typography/opentype/spec/featurelist Requires libraqm.

        New in version 4.2.0.

      - language –

        Language of the text. Different languages may use different glyph shapes or ligatures. This parameter tells the font which language the text is in, and to apply the correct substitutions as appropriate, if available. It should be a BCP 47 language code Requires libraqm.

        New in version 6.0.0.

      - stroke_width –

        The width of the text stroke.

        New in version 6.2.0.

    Returns

      (width, height)

  getsize_multiline(text, direction=None, spacing=4, features=None, language=None, stroke_width=0)

    Returns width and height (in pixels) of given text if rendered in font with provided direction, features, and language, while respecting newline characters.

    Parameters

      - text – Text to measure.

      - direction – Direction of the text. It can be ‘rtl’ (right to left), ‘ltr’ (left to right) or ‘ttb’ (top to bottom). Requires libraqm.

      - spacing – The vertical gap between lines, defaulting to 4 pixels.

      - features – A list of OpenType font features to be used during text layout. This is usually used to turn on optional font features that are not enabled by default, for example ‘dlig’ or ‘ss01’, but can be also used to turn off default font features for example ‘-liga’ to disable ligatures or ‘-kern’ to disable kerning. To get all supported features, see https://docs.microsoft.com/en-us/typography/opentype/spec/featurelist Requires libraqm.

      - language –

        Language of the text. Different languages may use different glyph shapes or ligatures. This parameter tells the font which language the text is in, and to apply the correct substitutions as appropriate, if available. It should be a BCP 47 language code Requires libraqm.

        New in version 6.0.0.

      - stroke_width –

        The width of the text stroke.

        New in version 6.2.0.

    Returns

      (width, height)

  set_variation_by_axes(axes)
    Parameters

      axes – A list of values for each axis.

    Raises

      OSError – If the font is not a variation font.

  set_variation_by_name(name)
    Parameters

      name – The name of the style.

    Raises

      OSError – If the font is not a variation font.

class PIL.ImageFont.TransposedFont(font, orientation=None)

  Wrapper for writing rotated or mirrored text

## Constants

PIL.ImageFont.LAYOUT_BASIC

  Use basic text layout for TrueType font. Advanced features such as text direction are not supported.

PIL.ImageFont.LAYOUT_RAQM

  Use Raqm text layout for TrueType font. Advanced features are supported.

  Requires Raqm, you can check support using `PIL.features.check_feature()` with `feature="raqm"`.

## Constants

PIL.ImageFont.MAX_STRING_LENGTH

  Set to 1,000,000, to protect against potential DOS attacks. Pillow will raise a `ValueError` if the number of characters is over this limit. The check can be disabled by setting `ImageFont.MAX_STRING_LENGTH = None`.