Skip to content
quickthumb
All documentation

Installation

quickthumb needs Python 3.11 or later.

Isolated environment

Install quickthumb 0.8.0 in a virtual environment outside any quickthumb checkout:

mkdir -p quickthumb-first-export
cd quickthumb-first-export
python3 -m venv .venv
source .venv/bin/activate
python -m pip install "quickthumb==0.8.0"

On Windows, activate with .venv\Scripts\activate instead. The shell commands above use Bash/Zsh. Installing dependencies needs the package index or a populated local cache. Running outside the checkout ensures Python imports the installed wheel rather than the source directory.

Existing uv project

uv add "quickthumb[cli]>=0.8.0"

The base package is enough for PNG, JPEG, WebP, GIF, SVG output, and HTML. Try rendering your first episode cards before adding optional renderers. The example needs no font or image downloads after installation.

Optional extras

Some features need extra packages. Install them by name, for example pip install "quickthumb[svg,pdf]".

Extra Use it for
svg Drawing SVG files as layers. Exporting to SVG does not need this extra.
pdf PDF export and optional PDF fidelity checks.
pptx PowerPoint export.
lottie Supported text outlines in Canvas Lottie exports; shape-only Lottie does not need it.
rembg Removing image backgrounds. The first use downloads a model of about 170 MB.
cli The quickthumb command, including render, lint, watch, and doctor.

MP4, WebM, and MOV export also need ffmpeg, which is a system program rather than a Python package:

brew install ffmpeg      # macOS
sudo apt install ffmpeg  # Debian / Ubuntu

MOV requires an FFmpeg build with the prores_ks encoder.

SVG layers also need the native Cairo library; the Python extra does not install system libraries. See CairoSVG installation for platform requirements.

Check your environment

quickthumb doctor (from the cli extra) discovers requirements for an export:

quickthumb doctor            # PNG, the default
quickthumb doctor mp4        # discover ffmpeg/ffprobe
quickthumb doctor pdf --spec card.json -o out/card.pdf

It exits with status 1 if a required check fails, so it also works as a CI step. It does not render a test file or certify native libraries, codec support, or visual fidelity. Run the intended export as well. See Diagnostics & CLI for details.

Development checkout

To try unreleased changes, run uv build in the repository, then install the resulting wheel into the isolated environment using its absolute path, for example python -m pip install "/path/to/dist/quickthumb-0.8.0-py3-none-any.whl[cli]". This installs the checkout's code rather than downloading the published release. See the 0.8.0 migration notes when upgrading from 0.7.0.

Environment variables

All optional.

Variable What it does
QUICKTHUMB_FONT_DIR Folder of font files to search when font is a family name
QUICKTHUMB_DEFAULT_FONT Font to use when a text layer has no font
QUICKTHUMB_FONT_CACHE_DIR Where downloaded fonts are cached (default: the system temp folder)
QUICKTHUMB_ASSET_CACHE_DIR Where downloaded images are cached (default: the system temp folder)
QUICKTHUMB_ASSET_MAX_AGE Seconds before a cached download is refreshed. Unset means never.
QUICKTHUMB_ASSET_OFFLINE Set to 1 to never download; only cached files are used
QUICKTHUMB_FFMPEG, QUICKTHUMB_FFPROBE Paths to ffmpeg and ffprobe if they aren't on PATH

Remote assets and caching explains the cache in more detail.