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)[source]#

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)[source]#

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)[source]#

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. On Windows, be aware that FreeType will keep the file open as long as the FreeTypeFont object exists. Windows limits the number of files that can be open in C at once to 512, so if many fonts are opened simultaneously and that limit is approached, an OSError may be thrown, reporting that FreeType “cannot open resource”. A workaround would be to copy the file(s) into memory, and open that instead.

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 pixels.

  • 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. If it is available, Raqm layout will be used by default. Otherwise, basic layout will be used.

    Raqm layout is recommended for all non-English text. If Raqm layout is not required, basic layout will have better performance.

    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.

  • ValueError – If the font size is not greater than zero.

PIL.ImageFont.load_default(size=None)[source]#

If FreeType support is available, load a version of Aileron Regular, https://dotcolon.net/font/aileron, with a more limited character set.

Otherwise, load a “better than nothing” font.

New in version 1.1.4.

Parameters:

size

The font size of Aileron Regular.

New in version 10.1.0.

Returns:

A font object.

Methods#

class PIL.ImageFont.ImageFont[source]#

PIL font wrapper

getbbox(text, *args, **kwargs)[source]#

Returns bounding box (in pixels) of given text.

New in version 9.2.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.

Returns:

(left, top, right, bottom) bounding box

getlength(text, *args, **kwargs)[source]#

Returns length (in pixels) of given text. This is the amount by which following text should be offset.

New in version 9.2.0.

getmask(text, mode='', *args, **kwargs)[source]#

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.

class PIL.ImageFont.FreeTypeFont(font: bytes | str | Path | BinaryIO | None = None, size: float = 10, index: int = 0, encoding: str = '', layout_engine: Layout | None = None)[source]#

FreeType font wrapper (requires _imagingft service)

font_variant(font=None, size=None, index=None, encoding=None, layout_engine=None)[source]#

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()[source]#
Returns:

A list of the axes in a variation font.

Raises:

OSError – If the font is not a variation font.

get_variation_names()[source]#
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)[source]#

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://learn.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, specifically la for horizontal text and lt for vertical text. See Text anchors for details.

Returns:

(left, top, right, bottom) bounding box

getlength(text, mode='', direction=None, features=None, language=None)[source]#

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://learn.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:

Either width for horizontal text, or height for vertical text.

getmask(text, mode='', direction=None, features=None, language=None, stroke_width=0, anchor=None, ink=0, start=None)[source]#

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://learn.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, specifically la for horizontal text and lt for vertical text. See Text anchors for details.

    New in version 8.0.0.

  • ink

    Foreground ink for rendering in RGBA mode.

    New in version 8.0.0.

  • start

    Tuple of horizontal and vertical offset, as text may render differently when starting at fractional coordinates.

    New in version 9.4.0.

Returns:

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

getmask2(text, mode='', direction=None, features=None, language=None, stroke_width=0, anchor=None, ink=0, start=None, *args, **kwargs)[source]#

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://learn.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, specifically la for horizontal text and lt for vertical text. See Text anchors for details.

    New in version 8.0.0.

  • ink

    Foreground ink for rendering in RGBA mode.

    New in version 8.0.0.

  • start

    Tuple of horizontal and vertical offset, as text may render differently when starting at fractional coordinates.

    New in version 9.4.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()[source]#
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()[source]#
Returns:

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

set_variation_by_axes(axes)[source]#
Parameters:

axes – A list of values for each axis.

Raises:

OSError – If the font is not a variation font.

set_variation_by_name(name)[source]#
Parameters:

name – The name of the style.

Raises:

OSError – If the font is not a variation font.

class PIL.ImageFont.TransposedFont(font, orientation=None)[source]#

Wrapper for writing rotated or mirrored text

getbbox(text, *args, **kwargs)[source]#
getlength(text, *args, **kwargs)[source]#
getmask(text, mode='', *args, **kwargs)[source]#

Constants#

class PIL.ImageFont.Layout[source]#
BASIC#

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

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".

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.