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