Fast, friendly image processing for Python web apps and SaaS. Nitro Image wraps Pillow with a chainable, lazy-evaluated pipeline so you can resize, convert, optimize, and generate responsive image sets with one fluent call.
pip install nitro-imageOptional extras:
pip install nitro-image[url] # Load images from URLs (httpx)
pip install nitro-image[avif] # AVIF format support
pip install nitro-image[blur] # BlurHash generation
pip install nitro-image[all] # Everything abovefrom nitro_img import Image
Image("photo.jpg").resize(800).webp(quality=80).save("photo.webp")- Chainable API - Fluent, readable pipelines instead of verbose PIL boilerplate
- Lazy Execution - Operations queue up and only run on output (
.save(),.to_bytes(), etc.) - Format Conversion - JPEG, PNG, WebP, GIF, and optional AVIF
- Smart Resizing -
resize,thumbnail,cover,containwith upscale control - Responsive Sets - Generate multiple widths for
srcsetin one call - Placeholders - LQIP data URIs, dominant colors, palettes, SVG, and BlurHash
- Overlays - Watermarks and text with position, opacity, and scale control
- Batch Processing - Glob-based batch with optional thread parallelism
- Framework Integrations - One-line response helpers for Django, Flask, and FastAPI
- Presets - Opinionated one-call helpers for thumbnails, avatars, OG images, and banners
- Optimization - Target-size encoding with automatic quality tuning
Add Nitro Image knowledge to your AI coding assistant:
npx skills add nitrosh/nitro-imageThis enables AI assistants like Claude Code to understand Nitro Image and generate correct nitro_img code.
With Pillow alone:
from PIL import Image
img = Image.open("photo.jpg")
img = img.convert("RGB")
width, height = img.size
new_height = int(height * (800 / width))
img = img.resize((800, new_height), Image.LANCZOS)
img.save("photo.webp", "WEBP", quality=80)With Nitro Image:
from nitro_img import Image
Image("photo.jpg").resize(800).webp(quality=80).save("photo.webp")Operations queue up and only run when you call an output method like .save() or .to_bytes(), so a long chain still touches the pixels once.
Each chained call returns a new Image and leaves the one you called it on alone, so you can branch off a shared base:
base = Image("photo.jpg").strip_metadata()
base.resize(400).webp().save("small.webp")
base.resize(1600).jpeg().save("large.jpg")That also means a bare img.resize(400) on its own line does nothing - keep the return value. This changed in 2.0; in 1.x chained calls modified the image in place.
Image("photo.jpg").resize(800).save("resized.jpg")
Image("photo.jpg").thumbnail(200, 200).save("thumb.jpg")
Image("photo.jpg").cover(400, 400).save("square.jpg")
Image("photo.jpg").contain(400, 400).save("contained.jpg")
Image("photo.jpg").crop(500, 400, anchor="center").save("cropped.jpg")Enlarging an image makes it blurry, so none of the resize methods do it unless you ask. That means the output can be smaller than the size you passed, with no error or warning:
| Call, on a 1200x800 source | Result | With allow_upscale=True |
|---|---|---|
resize(3000) |
1200x800, unchanged | 3000x2000 |
thumbnail(2000, 2000) |
1200x800, unchanged | 2000x1333 |
cover(1080, 1350) |
1080x800, cropped but not enlarged | 1080x1350 |
contain(2000, 2000) |
2000x2000 canvas, image at 1200x800 inside it | 2000x2000, image fills the width |
If you need an exact size every time, for a social card or a fixed grid, allow it per call or for the whole process:
Image("photo.jpg").cover(1080, 1350, allow_upscale=True).save("story.jpg")
from nitro_img import config
config.update(allow_upscale=True)The presets that promise a fixed size (avatar, og_image, banner)
already upscale for you. save_responsive skips widths larger than the
source, so asking for [800, 1600] from an 800px image writes one file.
Image("photo.jpg").webp(quality=80).save("photo.webp")
Image("photo.jpg").png().save("photo.png")
Image("photo.jpg").jpeg(quality=90).save("photo.jpg")
path = Image("photo.jpg").auto_format().save("photo.webp") # picks the best format and fixes the suffix to matchImage("photo.jpg").brightness(1.2).contrast(1.1).save("enhanced.jpg")
Image("photo.jpg").sharpen(1.5).save("sharp.jpg")
Image("photo.jpg").blur(2.0).save("blurred.jpg")
Image("photo.jpg").grayscale().save("gray.jpg")
Image("photo.jpg").sepia().save("sepia.jpg")
Image("photo.jpg").rounded_corners(20).png().save("rounded.png")Image("photo.jpg").watermark("logo.png", position="bottom-right", opacity=0.5).save("watermarked.jpg")
Image("photo.jpg").text_overlay("Sample", font_size=48).save("labeled.jpg")widths = Image("photo.jpg").responsive([400, 800, 1200, 1600])
# Returns {400: bytes, 800: bytes, 1200: bytes, 1600: bytes}
Image("photo.jpg").webp().save_responsive("output/", [400, 800, 1200], name="hero")
# Saves output/hero_400.webp, output/hero_800.webp, output/hero_1200.webp# Placeholders reflect any queued operations, e.g. .crop(400, 400).lqip()
Image("photo.jpg").lqip() # Low-quality base64 data URI
Image("photo.jpg").dominant_color() # "#3a6b8c"
Image("photo.jpg").color_palette(5) # ["#3a6b8c", "#d4a574", ...]
Image("photo.jpg").svg_placeholder() # SVG with dominant color
Image("photo.jpg").blurhash() # "LKO2:N%2Tw=w]~RBVZRi..."Image("photo.jpg").optimize(target_kb=200)
# Returns the encoded bytes, auto-tuning quality to hit the target sizePresets are opinionated one-call helpers. They take a source (path, bytes, or file-like) and return encoded bytes.
from nitro_img import presets, Image
presets.thumbnail("photo.jpg") # 200x200 WebP
presets.avatar("photo.jpg", size=128) # 128px circle-cropped PNG
presets.og_image("photo.jpg") # 1200x630 JPEG social card
presets.banner("photo.jpg") # 1920x400 JPEG banner
presets.avatar_placeholder("SN") # Initials avatar
# Presets are also available via Image.preset for convenience:
Image.preset.thumbnail("photo.jpg")from nitro_img import BatchImage
BatchImage("photos/*.jpg").resize(800).webp().save("output/{name}.webp")
BatchImage("photos/*.jpg").resize(800).jpeg().save("output/{name}.jpg", parallel=True){name} in the save pattern is replaced with each source file's stem.
# Django
return Image("photo.jpg").resize(400).webp().to_django_response()
# Flask
return Image("photo.jpg").resize(400).webp().to_flask_response()
# FastAPI / Starlette
return Image("photo.jpg").resize(400).webp().to_fastapi_response()Image("photo.jpg") # File path
Image.from_bytes(raw_bytes) # Bytes
Image.from_base64(b64_string) # Base64 string
Image.from_url("https://example.com/img") # URL (requires httpx)
Image.from_file(file_object) # File-like objectimg = Image("photo.jpg").resize(400).webp()
img.save("output.webp") # Save to file
img.to_bytes() # Raw bytes
img.to_base64() # Base64 encoded string
img.to_data_uri() # data:image/webp;base64,...
img.to_response() # {"body": bytes, "content_type": str, "content_length": int}All operations are chainable and lazily evaluated:
(
Image("photo.jpg")
.resize(800)
.brightness(1.1)
.contrast(1.05)
.sharpen(1.2)
.sepia()
.rounded_corners(10)
.png()
.save("final.png")
)from nitro_img import config
config.update(
default_jpeg_quality=85,
default_webp_quality=80,
default_png_compression=6,
allow_upscale=False,
auto_orient=True,
strip_metadata=False,
max_output_dimensions=10_000,
)- Python 3.10+
- Pillow 10.1+
- nitro-ui - Build HTML with Python, not strings
- nitro-cli - Python-powered static site generator
- nitro-datastore - Schema-free JSON data store with dot notation access
- nitro-dispatch - Framework-agnostic plugin system
- nitro-validate - Dependency-free data validation
This project is licensed under the BSD 3-Clause License. See the LICENSE file for details.