Skip to content
quickthumb
All documentation

FAQ

Installation

Which Python versions are supported?

Python 3.11 or later. The package is classified for 3.11 and 3.12, and CI runs on 3.11. This includes background removal (the rembg extra).

The quickthumb command isn't found

The command line tool is an optional extra: pip install "quickthumb[cli]". Installation lists every extra.

Why does my SVG layer raise RenderingError?

Drawing SVG files needs the svg extra: pip install "quickthumb[svg]". Exporting a canvas to SVG doesn't.

Canvas and layers

What happens if I render a canvas with no layers?

You get a fully transparent image of the canvas size. It isn't an error.

Why does a group child raise "group children must not set position"?

A group positions its children itself. Remove position from the child and place the group instead:

canvas.group(
    children=[{"type": "text", "content": "TITLE", "size": 96, "color": "#FFFFFF"}],
    position=("8%", "50%"),
    align=("left", "middle"),
)

A child's align is ignored too. Use the group's item_align to line children up across the group.

How do I check a design for problems before rendering?

Call canvas.diagnose(), or run quickthumb lint spec.json on a JSON spec. It reports text that is too small or off the canvas, low contrast, hidden layers, and more. See Diagnostics & CLI.

Text and fonts

My text runs off the canvas

Set max_width so it wraps:

canvas.text(content="A longer title that needs two lines", size=72, color="#FFFFFF", max_width="60%")

Add auto_scale=True (with max_width, max_height, or both) to shrink the text until it fits instead.

I set bold=True and weight=900 and got an error

They set the same thing, so use one. weight is more precise: TextPart(text="STRONG", weight=900).

How do I use a Google Font?

Name it and set font_source="google". It is downloaded once and cached, and weight picks the matching file:

canvas.text(content="Hello", font="Inter", font_source="google", weight=800, size=72, color="#FFFFFF")

You can also pass the URL of a font file, or point QUICKTHUMB_FONT_DIR at a folder of fonts. See Webfonts & Background Removal.

Images

Can I use images from a URL?

Yes. background(image=...) and image(path=...) accept http(s) URLs. They are downloaded and cached while rendering. To control the cache, see Remote assets and caching.

How do I remove the background behind a person?

Set remove_background=True on the image layer. It needs the rembg extra:

canvas.image(path="portrait.jpg", position=("75%", "55%"), width=420, height=520, remove_background=True)

What's the difference between cover, contain, and fill?

cover fills the box and crops what doesn't fit. contain fits the whole image inside the box and leaves empty space. fill stretches the image to the box, ignoring its proportions.

Output

Which formats can I export?

The format comes from the file extension you pass to render():

Kind Formats Needs
Images PNG, JPEG, WebP
Vector and documents SVG, PDF, PPTX pdf / pptx extras for PDF and PPTX
Web HTML
Animation GIF, MP4, WebM ffmpeg for MP4 and WebM

See Choose an output format for a first export and the export reference for what each format keeps and loses.

Can I set quality for a PNG?

No. quality only applies to JPEG and WebP; passing it for PNG raises RenderingError.

How do I get the image without writing a file?

png_base64 = canvas.to_base64(format="PNG")
jpeg_data_url = canvas.to_data_url(format="JPEG", quality=90)

JSON

Can I pass a dict to Canvas.from_json()?

No, it takes a JSON string. Convert first with json.dumps(data).

Why does to_json() raise ValidationError?

The canvas has a .custom(fn) layer. A Python function can't be written to JSON, so remove that layer first.

My theme block disappeared after to_json()

Theme tokens are replaced with their values when the spec is loaded, so to_json() writes the values and no theme block. Keep your original spec file if you want to keep editing the tokens.

Errors

What do the different errors mean?

  • ValidationError: an argument or spec field is invalid. Raised as soon as you add the layer or load the spec.
  • RenderingError: something failed while drawing, such as a download.
  • MissingAssetError: a local file the spec refers to doesn't exist.

Every error has details with a stable code, the JSON Pointer of the field, and the layer id. See Structured Errors.