libvips Image Processing

Fast, memory-efficient image processing using libvips via pyvips. Supports 300+ operations including resize, crop, rotate, convert, watermark, composite, and more. Ideal for batch processing large images.

When to Use

• Resize, crop, or thumbnail images efficiently
• Convert between formats (JPEG, PNG, WebP, AVIF, HEIC, TIFF, PDF, SVG)
• Add watermarks or text overlays
• Batch process multiple images
• Handle large images with low memory usage
• Create image pipelines for web optimization

Quick Start

Install (One-Click)

# Recommended: Auto-detect OS and install everything
./scripts/install.sh

The install script will:

1. Detect your OS (macOS, Linux, Windows)
2. Install libvips system library
3. Install pyvips via uv (preferred) or pip
4. Verify the installation

Manual Install

macOS (Homebrew):

brew install vips
uv pip install pyvips  # preferred
# or: pip install pyvips

Ubuntu/Debian:

sudo apt-get install libvips-dev
uv pip install pyvips  # preferred
# or: pip install pyvips

Fedora/RHEL:

sudo dnf install vips-devel
uv pip install pyvips

Arch Linux:

sudo pacman -S libvips
uv pip install pyvips

Windows (PowerShell, recommended):

# One-click install (downloads libvips + installs pyvips)
.\scripts\install.ps1

Windows (Manual):

# Option 1: winget (if available)
winget install libvips.libvips

# Option 2: scoop
scoop install libvips

# Option 3: Manual download
# Download from https://github.com/libvips/libvips/releases
# Extract to C:\vips or %LOCALAPPDATA%\vips
# Add bin\ to PATH

# Install pyvips
uv pip install pyvips
# or: pip install pyvips

Install uv (if not installed):

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
irm https://astral.sh/uv/install.ps1 | iex

Basic Usage

macOS/Linux - Using run.sh wrapper (recommended):

./scripts/run.sh vips_tool.py resize input.jpg output.jpg --width 800
./scripts/run.sh vips_tool.py convert input.jpg output.webp --quality 85
./scripts/run.sh vips_tool.py thumbnail input.jpg thumb.jpg --size 200
./scripts/run.sh vips_batch.py resize ./input ./output --width 800

Windows - Using run.bat wrapper (recommended):

.\scripts\run.bat vips_tool.py resize input.jpg output.jpg --width 800
.\scripts\run.bat vips_tool.py convert input.jpg output.webp --quality 85
.\scripts\run.bat vips_tool.py thumbnail input.jpg thumb.jpg --size 200
.\scripts\run.bat vips_batch.py resize .\input .\output --width 800

Cross-platform - Using uv (after uv sync):

uv run python scripts/vips_tool.py resize input.jpg output.jpg --width 800