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.

PIL.ImageFont.load_default()[source]

Load a “better than nothing” default font.

New in version 1.1.4.

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.

getsize(text, *args, **kwargs)[source]

Deprecated since version 9.2.0.

Use getbbox() or getlength() instead.

See deprecations for more information.

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)[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. See Text anchors for valid values.

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:

Width for horizontal, 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. 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.

  • 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='', fill=<object object>, 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.

  • fill –

    Optional fill function. By default, an internal Pillow function will be used.

    Deprecated. This parameter will be removed in Pillow 10 (2023-07-01).

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

  • 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)

getoffset(text)[source]

Deprecated since version 9.2.0.

Use getbbox() instead.

See deprecations for more information.

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

Deprecated since version 9.2.0.

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.

See deprecations for more information.

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

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

Returns:

(width, height)

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

Deprecated since version 9.2.0.

Use ImageDraw.multiline_textbbox() instead.

See deprecations for more information.

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

    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)[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]
getsize(text, *args, **kwargs)[source]

Deprecated since version 9.2.0.

Use getbbox() or getlength() instead.

See deprecations for more information.

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.