API Reference

Top-level Functions

memeplotlib.meme(template, *lines, font=None, color=None, outline_color=None, outline_width=None, fontsize=None, style=None, show=True, savefig=None, figsize=None, dpi=None, ax=None)

Create a meme from a template with text lines.

This is the main entry point for creating memes. The template can be:

• A memegen template ID (e.g., "buzz", "drake", "doge")

• A local file path to an image

• An HTTP(S) URL to an image

Parameters:

• template (str) – Template identifier – memegen ID, file path, or URL.

• *lines (str) – Text lines for each text position (top, bottom, etc.).

• font (str or None, optional) – Font family name (default: "impact").

• color (str or None, optional) – Text fill color (default: "white").

• outline_color (str or None, optional) – Text outline color (default: "black").

• outline_width (float or None, optional) – Outline stroke width (default: 2.0).

• fontsize (float or None, optional) – Font size in points. Auto-calculated if None.

• style (str or None, optional) – Text transform – "upper", "lower", or "none" (default: "upper").

• show (bool, optional) – Whether to call plt.show() (default: True).

• savefig (str, Path, or None, optional) – Path to save the meme image to.

• figsize (tuple of (float, float) or None, optional) – Figure size as (width, height) in inches.

• dpi (int or None, optional) – Dots per inch (default: 150).

• ax (Axes or None, optional) – Existing matplotlib Axes to render onto.

Returns:

The matplotlib Figure and Axes for further customization.

Return type:

tuple of (Figure, Axes)

Examples

>>> import memeplotlib as memes
>>> memes.meme("buzz", "memes", "memes everywhere")  

>>> memes.meme("drake", "writing tests", "shipping to prod",
...            font="impact", color="yellow", show=False)  

Example output:

memeplotlib.memify(fig, *lines, position='top-bottom', font=None, color=None, outline_color=None, outline_width=None, fontsize=None, style=None, show=True, savefig=None)

Add meme-style text to an existing matplotlib figure.

Overlays bold, outlined text on top of any matplotlib figure – useful for turning plots, charts, or other visualizations into memes.

Parameters:

• fig (Figure) – The matplotlib figure to add text to.

• *lines (str) – Text lines to overlay.

• position (str, optional) – Layout – "top-bottom" (default), "top", "bottom", or "center".

• font (str or None, optional) – Font family name.

• color (str or None, optional) – Text fill color.

• outline_color (str or None, optional) – Text outline color.

• outline_width (float or None, optional) – Outline stroke width.

• fontsize (float or None, optional) – Font size in points (auto if None).

• style (str or None, optional) – Text transform – "upper", "lower", or "none".

• show (bool, optional) – Whether to call plt.show().

• savefig (str, Path, or None, optional) – Path to save the result to.

Returns:

The modified Figure.

Return type:

Figure

Examples

>>> import matplotlib.pyplot as plt
>>> import memeplotlib as memes
>>> fig, ax = plt.subplots()  
>>> ax.plot([1, 2, 3], [1, 4, 9])  
>>> memes.memify(fig, "stonks")  

Example output:

Meme Class

class memeplotlib.Meme(template, *lines, font=None, color=None, outline_color=None, outline_width=None, fontsize=None, style=None)

Bases: object

A meme builder with a fluent (chainable) API.

Parameters:

• template (str or Template) – Template identifier (memegen ID, file path, URL) or a Template instance.

• *lines (str) – Initial text lines.

• font (str or None, optional) – Font family name.

• color (str or None, optional) – Text fill color.

• outline_color (str or None, optional) – Text outline color.

• outline_width (float or None, optional) – Outline stroke width.

• fontsize (float or None, optional) – Font size in points.

• style (str or None, optional) – Text transform – "upper", "lower", or "none".

Examples

>>> from memeplotlib import Meme
>>> Meme("buzz").top("memes").bottom("memes everywhere").show()  

>>> m = Meme("drake")  
>>> m.top("writing tests")  
>>> m.bottom("shipping to prod")  
>>> fig, ax = m.render()  
>>> m.save("output.png")  

top(text)

Set the top text line (index 0).

Parameters:

text (str) – The text to place at the top of the meme.

Returns:

Self, for method chaining.

Return type:

Meme

bottom(text)

Set the bottom text line (index 1).

Parameters:

text (str) – The text to place at the bottom of the meme.

Returns:

Self, for method chaining.

Return type:

Meme

text(index, text)

Set text at a specific line index.

Parameters:

• index (int) – Zero-based line index.

• text (str) – The text to place at the given position.

Returns:

Self, for method chaining.

Return type:

Meme

render(ax=None, figsize=None, dpi=None)

Render the meme and return the Figure and Axes.

Parameters:

• ax (Axes or None, optional) – Existing axes to render onto.

• figsize (tuple of (float, float) or None, optional) – Figure size in inches (width, height).

• dpi (int or None, optional) – Dots per inch.

Returns:

The rendered matplotlib Figure and Axes.

Return type:

tuple of (Figure, Axes)

show()

Render and display the meme.

Calls render() if the meme has not been rendered yet, then displays the figure with matplotlib.pyplot.show().

Return type:

None

save(path, dpi=None, **kwargs)

Render and save the meme to a file.

Parameters:

• path (str or Path) – Output file path (e.g., "meme.png").

• dpi (int or None, optional) – Dots per inch for the saved image.

• **kwargs – Additional keyword arguments passed to matplotlib.figure.Figure.savefig().

Return type:

None

Example output:

Configuration

memeplotlib.config = MemeplotlibConfig()

Global configuration for memeplotlib.

Modify this object to change defaults for all meme creation calls. Individual function calls can still override via keyword arguments.

memeplotlib.api_base

Base URL for the memegen API.

Type:

str

memeplotlib.font

Default font family name.

Type:

str

memeplotlib.color

Default text fill color.

Type:

str

memeplotlib.outline_color

Default text outline color.

Type:

str

memeplotlib.outline_width

Default outline stroke width.

Type:

float

memeplotlib.fontsize

Base font size in points for auto-sizing.

Type:

float

memeplotlib.dpi

Default dots per inch for rendering.

Type:

int

memeplotlib.style

Default text transform ("upper", "lower", or "none").

Type:

str

memeplotlib.cache_enabled

Whether disk caching is enabled.

Type:

bool

memeplotlib.cache_dir

Custom cache directory path, or None for the platform default.

Type:

str or None

Examples

>>> import memeplotlib as memes
>>> memes.config.font = "comic"  
>>> memes.config.color = "yellow"  

class memeplotlib._config.MemeplotlibConfig(api_base='https://api.memegen.link', font='impact', color='white', outline_color='black', outline_width=2.0, fontsize=72.0, dpi=150, style='upper', cache_enabled=True, cache_dir=None)

Bases: object

Global configuration for memeplotlib.

Modify this object to change defaults for all meme creation calls. Individual function calls can still override via keyword arguments.

Parameters:

• api_base (str)

• font (str)

• color (str)

• outline_color (str)

• outline_width (float)

• fontsize (float)

• dpi (int)

• style (str)

• cache_enabled (bool)

• cache_dir (str | None)

api_base

Base URL for the memegen API.

Type:

str

font

Default font family name.

Type:

str

color

Default text fill color.

Type:

str

outline_color

Default text outline color.

Type:

str

outline_width

Default outline stroke width.

Type:

float

fontsize

Base font size in points for auto-sizing.

Type:

float

dpi

Default dots per inch for rendering.

Type:

int

style

Default text transform ("upper", "lower", or "none").

Type:

str

cache_enabled

Whether disk caching is enabled.

Type:

bool

cache_dir

Custom cache directory path, or None for the platform default.

Type:

str or None

Examples

>>> import memeplotlib as memes
>>> memes.config.font = "comic"  
>>> memes.config.color = "yellow"  

api_base: str = 'https://api.memegen.link'

font: str = 'impact'

color: str = 'white'

outline_color: str = 'black'

outline_width: float = 2.0

fontsize: float = 72.0

dpi: int = 150

style: str = 'upper'

cache_enabled: bool = True

cache_dir: str | None = None

Templates

class memeplotlib.Template(id, name, image_url, text_positions=<factory>, keywords=<factory>, example=<factory>, _image_array=None)

Bases: object

A meme template with a background image and text position metadata.

Parameters:

• id (str)

• name (str)

• image_url (str)

• text_positions (list[TextPosition])

• keywords (list[str])

• example (list[str])

• _image_array (ndarray | None)

id

Template identifier (e.g., "buzz", "drake").

Type:

str

name

Human-readable display name.

Type:

str

image_url

URL or local file path to the background image.

Type:

str

text_positions

Regions where text lines are rendered.

Type:

list of TextPosition

keywords

Search keywords associated with the template.

Type:

list of str

example

Example text lines for the template.

Type:

list of str

classmethod from_memegen(template_id, api_base=None)

Fetch template metadata and blank image from the memegen API.

Parameters:

• template_id (str) – The memegen template ID (e.g., "buzz", "drake").

• api_base (str or None, optional) – Override the API base URL.

Returns:

A Template instance with metadata populated from the API.

Return type:

Template

Raises:

TemplateNotFoundError – If the template ID doesn’t exist in the memegen API.

Examples

>>> t = Template.from_memegen("buzz")  
>>> t.name  
'Buzz Lightyear'

classmethod from_image(path_or_url, lines=2, name='')

Create a template from a local image file or URL.

Parameters:

• path_or_url (str) – Path to a local image file, or an HTTP(S) URL.

• lines (int, optional) – Number of text lines, which determines the number of text positions (default: 2).

• name (str, optional) – Display name for the template. Defaults to the file stem.

Returns:

A Template instance backed by the given image.

Return type:

Template

Examples

>>> t = Template.from_image("photo.jpg")  
>>> t = Template.from_image("https://example.com/img.png", lines=3)  

get_image(cache=None)

Return the template background image as a NumPy RGBA array.

Downloads from the image URL if not already loaded or cached.

Parameters:

cache (TemplateCache or None, optional) – Cache instance for storing/retrieving downloaded images.

Returns:

RGBA image array with shape (height, width, 4).

Return type:

numpy.ndarray

class memeplotlib._template.TextPosition(anchor_x=0.0, anchor_y=0.0, scale_x=1.0, scale_y=0.2, align='center', style='upper', angle=0.0)

Bases: object

Defines where and how a text line is rendered on a template.

All coordinates are fractional (0.0 to 1.0) relative to the image dimensions. (0, 0) is the top-left corner.

Parameters:

• anchor_x (float)

• anchor_y (float)

• scale_x (float)

• scale_y (float)

• align (str)

• style (str)

• angle (float)

anchor_x

Left edge of the text box (0.0 to 1.0).

Type:

float

anchor_y

Top edge of the text box (0.0 to 1.0).

Type:

float

scale_x

Width of the text box as a fraction of image width.

Type:

float

scale_y

Height of the text box as a fraction of image height.

Type:

float

align

Horizontal text alignment ("center", "left", "right").

Type:

str

style

Default text style for this position ("upper", "lower", "none").

Type:

str

angle

Text rotation angle in degrees.

Type:

float

anchor_x: float = 0.0

anchor_y: float = 0.0

scale_x: float = 1.0

scale_y: float = 0.2

align: str = 'center'

style: str = 'upper'

angle: float = 0.0

class memeplotlib.TemplateRegistry(api_base=None, cache=None)

Bases: object

Registry that discovers and caches templates from the memegen API.

Parameters:

• api_base (str or None, optional) – Base URL for the memegen API. Uses config.api_base if None.

• cache (TemplateCache or None, optional) – Cache instance for storing template metadata.

Examples

>>> reg = TemplateRegistry()  
>>> results = reg.search("dog")  
>>> all_templates = reg.list_all()  

get(template_id)

Get a template by ID, fetching from the API if needed.

Parameters:

template_id (str) – The memegen template ID.

Returns:

The resolved template.

Return type:

Template

Raises:

TemplateNotFoundError – If the template ID is not found.

search(query)

Search templates by keyword, name, or ID.

Parameters:

query (str) – Search term to match against template IDs, names, and keywords (case-insensitive).

Returns:

Matching template metadata dicts.

Return type:

list of dict

list_all()

List all available templates.

Returns:

Full template catalog from the memegen API.

Return type:

list of dict

refresh()

Force re-fetch of the template catalog from the API.

Return type:

None

exception memeplotlib._template.TemplateNotFoundError

Bases: Exception

Raised when a template ID is not found in the memegen API.

Rendering

Matplotlib rendering pipeline for meme images.

memeplotlib._rendering.render_meme(template, lines, ax=None, figsize=None, dpi=None, font=None, color=None, outline_color=None, outline_width=None, fontsize=None, style=None, cache=None)

Render a meme image using matplotlib.

Parameters:

• template (Template) – The Template to render.

• lines (list of str) – Text lines for each text position.

• ax (Axes or None, optional) – Existing axes to render onto. A new figure is created if None.

• figsize (tuple of (float, float) or None, optional) – Figure size in inches (width, height).

• dpi (int or None, optional) – Dots per inch for rendering.

• font (str or None, optional) – Font family name.

• color (str or None, optional) – Text fill color.

• outline_color (str or None, optional) – Text outline color.

• outline_width (float or None, optional) – Outline stroke width.

• fontsize (float or None, optional) – Font size in points (auto if None).

• style (str or None, optional) – Text style ("upper", "lower", "none").

• cache (TemplateCache or None, optional) – Template cache for image retrieval.

Returns:

The matplotlib Figure and Axes containing the rendered meme.

Return type:

tuple of (Figure, Axes)

memeplotlib._rendering.render_memify(fig, lines, position='top-bottom', font=None, color=None, outline_color=None, outline_width=None, fontsize=None, style=None)

Add meme text overlay to an existing matplotlib figure.

Creates a transparent overlay axes spanning the full figure and draws meme-style text on top.

Parameters:

• fig (Figure) – The matplotlib figure to add text to.

• lines (list of str) – Text lines to overlay.

• position (str, optional) – Layout preset – "top-bottom" (default), "top", "bottom", or "center".

• font (str or None, optional) – Font family name.

• color (str or None, optional) – Text fill color.

• outline_color (str or None, optional) – Text outline color.

• outline_width (float or None, optional) – Outline stroke width.

• fontsize (float or None, optional) – Font size in points (auto if None).

• style (str or None, optional) – Text style ("upper", "lower", "none").

Returns:

The modified Figure with meme text overlay.

Return type:

Figure

Text Utilities

Text encoding and wrapping utilities for memeplotlib.

memeplotlib._text.encode_text_for_url(text)

Encode text for use in memegen API URLs.

Transforms special characters according to the memegen URL encoding scheme. Spaces become underscores, and other special characters use tilde-escapes.

Parameters:

text (str) – The plain text to encode.

Returns:

URL-encoded text suitable for memegen API URLs.

Return type:

str

Examples

>>> encode_text_for_url("hello world")
'hello_world'
>>> encode_text_for_url("one_two")
'one__two'

memeplotlib._text.decode_text_from_url(text)

Decode text from memegen API URL format back to plain text.

Reverses the encoding applied by encode_text_for_url().

Parameters:

text (str) – The URL-encoded text to decode.

Returns:

Plain text with special characters restored.

Return type:

str

Examples

>>> decode_text_from_url("hello_world")
'hello world'
>>> decode_text_from_url("one__two")
'one_two'

memeplotlib._text.wrap_text(text, max_chars_per_line=30)

Word-wrap text to fit within a bounding box.

Tries to balance line lengths for a visually appealing result. Returns text with newlines inserted at wrap points.

Parameters:

• text (str) – The text to wrap.

• max_chars_per_line (int, optional) – Maximum characters per line (default: 30).

Returns:

Wrapped text with \n at break points.

Return type:

str

memeplotlib._text.apply_style(text, style)

Apply text style transformation.

Parameters:

• text (str) – The raw text.

• style (str) – One of "upper", "lower", or "none".

Returns:

Transformed text.

Return type:

str

Examples

>>> apply_style("hello", "upper")
'HELLO'
>>> apply_style("HELLO", "lower")
'hello'
>>> apply_style("Hello", "none")
'Hello'

Caching

Disk and memory caching for template images and metadata.

class memeplotlib._cache.TemplateCache(cache_dir=None, max_memory=50)

Bases: object

Two-level cache: in-memory LRU + on-disk file cache.

Caches template catalog metadata and downloaded template images so that the memegen API is only hit once per template.

Parameters:

• cache_dir (Path or None, optional) – Directory for on-disk cache files. Uses the platform default (via platformdirs) if None.

• max_memory (int, optional) – Maximum number of images to keep in the in-memory LRU cache (default: 50).

get_catalog(ttl=86400)

Get cached template catalog if it exists and hasn’t expired.

Parameters:

ttl (int, optional) – Time-to-live in seconds (default: 86400, i.e. 24 hours).

Returns:

List of template metadata dicts, or None on cache miss or expiry.

Return type:

list of dict or None

set_catalog(templates)

Cache template catalog to disk with current timestamp.

Parameters:

templates (list of dict) – Template metadata dicts to cache.

Return type:

None

get_image(url)

Get cached template image as a NumPy array.

Checks the in-memory LRU cache first, then falls back to the on-disk file cache.

Parameters:

url (str) – The image URL used as the cache key.

Returns:

RGBA image array, or None on cache miss.

Return type:

numpy.ndarray or None

set_image(url, image_bytes)

Cache template image to disk and memory.

Parameters:

• url (str) – The image URL used as the cache key.

• image_bytes (bytes) – Raw image file bytes to store.

Return type:

None

clear()

Clear all caches (memory and disk).

Return type:

None