OG Image Configuration

All settings are optional and configured via environment variables. No changes to settings.py are required beyond the standard MEDIA_ROOT / MEDIA_URL.

Environment variables

Examples

# .env
 
# Store images in a custom subdirectory
OGIMAGE__MEDIA_SUBDIR=assets/og
 
# Disable cache in development (always re-renders)
OGIMAGE__CACHE_ENABLED=false
 
# Custom font cache (e.g. shared Docker volume)
DJANGO_CFG_FONTS_DIR=/var/cache/django_cfg/fonts

Fonts

Fonts are downloaded on first use and cached locally — nothing is bundled with the package. At Django startup all fonts begin downloading in background daemon threads, so they are ready by the time the first OG image request arrives.

Download locations:

If a download fails (no network, SSL error) the module falls back to a system font without raising an exception. To update font URLs, edit core/font_sources.py in the package source.

Django settings requirements

The module reads settings.MEDIA_ROOT and settings.MEDIA_URL — both must be set:

# settings.py
MEDIA_ROOT = BASE_DIR / "media"
MEDIA_URL = "/media/"

Both are configured automatically if you use djangocfg’s DjangoConfig.

Cache layout

Images are stored in a two-level sharded directory to avoid inode limits:

MEDIA_ROOT/
└── ogimage/
    └── ab/
        └── cd/
            └── abcdef1234...png

The path components (ab, cd) are the first 4 characters of the SHA256 cache key — the same sharding scheme Git uses for objects.

Cache key

The cache key is SHA256[:40] computed from a stable JSON representation of OGImageParams — excluding page_url. This means:

• Same visual params + same title → same cached file, regardless of the source page
• Changing page_url does not invalidate the cache
• Changing any visual param or content field produces a new file

Disabling cache

When OGIMAGE__CACHE_ENABLED=false, the view re-renders on every request and overwrites the file. Useful for visual development — change renderer code and refresh immediately.

Related

• Overview — quick start
• Presets — color scheme presets
• Layouts — layout presets
• Branding & Icons — logo, icons, get_branded_og_url