Custom Fonts for CircuitPython Displays

Learn how to generate bitmap fonts!

by Ruiz Brothers

published February 18, 2019, last edited June 29, 2025
last major update April 19, 2021

posted in CircuitPython

Save Download

Beginner

Project guide

Bitmap_Font Library

This library is used for decoding .pcf or .bdf font files into Bitmap objects suitable for showing on a screen.

Basic Usage

If you just want to get your font loaded and shown on a standard display, you can do so using the Adafruit_CircuitPython_Bitmap_Font library with the Adafruit_CircuitPython_Display_Text library. Paste a copy of your font .pcf or .bdf file on your CIRCUITPY drive. Inside of a directory named fonts is a good place to put it. But there is no strict requirement, the file can be anywhere on the drive.

Then the font can be loaded like this:

font = bitmap_font.load_font("fonts/my_font.bdf")

and then pass the font variable into the constructor for BitmapLabel or Label.

my_label = Label(font, text="Hello")

See the full example below:

Download Project Bundle

Copy Code

# SPDX-FileCopyrightText: 2021 ladyada for Adafruit Industries
# SPDX-License-Identifier: MIT

"""
This example uses adafruit_display_text.label to display text using a custom font
loaded by adafruit_bitmap_font
"""

import board
from adafruit_display_text import label

from adafruit_bitmap_font import bitmap_font

# use built in display (MagTag, PyPortal, PyGamer, PyBadge, CLUE, etc.)
# see guide for setting up external displays (TFT / OLED breakouts, RGB matrices, etc.)
# https://learn.adafruit.com/circuitpython-display-support-using-displayio/display-and-display-bus
display = board.DISPLAY

# NOTE: You must copy the fonts/ folder from the
# examples in the repo to your CIRCUITPY drive.
# try uncommenting different font files if you like
font_file = "fonts/LeagueSpartan-Bold-16.bdf"
# font_file = "fonts/Junction-regular-24.pcf"

# Set text, font, and color
text = "HELLO WORLD"
font = bitmap_font.load_font(font_file)
color = 0xFF00FF

# Create the tet label
text_area = label.Label(font, text=text, color=color)

# Set the location
text_area.x = 20
text_area.y = 20

# Show it
display.root_group = text_area

while True:
    pass

# SPDX-FileCopyrightText: 2021 ladyada for Adafruit Industries
# SPDX-License-Identifier: MIT

"""
This example uses adafruit_display_text.label to display text using a custom font
loaded by adafruit_bitmap_font
"""

import board
from adafruit_display_text import label

from adafruit_bitmap_font import bitmap_font

# use built in display (MagTag, PyPortal, PyGamer, PyBadge, CLUE, etc.)
# see guide for setting up external displays (TFT / OLED breakouts, RGB matrices, etc.)
# https://learn.adafruit.com/circuitpython-display-support-using-displayio/display-and-display-bus
display = board.DISPLAY

# NOTE: You must copy the fonts/ folder from the
# examples in the repo to your CIRCUITPY drive.
# try uncommenting different font files if you like
font_file = "fonts/LeagueSpartan-Bold-16.bdf"
# font_file = "fonts/Junction-regular-24.pcf"

# Set text, font, and color
text = "HELLO WORLD"
font = bitmap_font.load_font(font_file)
color = 0xFF00FF

# Create the tet label
text_area = label.Label(font, text=text, color=color)

# Set the location
text_area.x = 20
text_area.y = 20

# Show it
display.root_group = text_area

while True:
    pass

Page last edited June 29, 2025