Libvips Image

---
name: libvips-image
description: High-performance image processing with libvips. Use for resizing, converting, watermarking, thumbnails, and batch image operations with low memory usage.
metadata:
  author: agiseek
  version: "1.0.1"
---

# 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)

```bash
# 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):**
```bash
brew install vips
uv pip install pyvips  # preferred
# or: pip install pyvips
```

**Ubuntu/Debian:**
```bash
sudo apt-get install libvips-dev
uv pip install pyvips  # preferred
# or: pip install pyvips
```

**Fedora/RHEL:**
```bash
sudo dnf install vips-devel
uv pip install pyvips
```

**Arch Linux:**
```bash
sudo pacman -S libvips
uv pip install pyvips
```

**Windows (PowerShell, recommended):**
```powershell
# One-click install (downloads libvips + installs pyvips)
.\scripts\install.ps1
```

**Windows (Manual):**
```powershell
# 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):**
```bash
# 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):**
```bash
./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):**
```cmd
.\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`):**
```bash
uv run python scripts/vips_tool.py resize input.jpg output.jpg --width 800
```

**Direct Python (if library paths are configured):**
```bash
python scripts/vips_tool.py resize input.jpg output.jpg --width 800
python scripts/vips_tool.py convert input.jpg output.webp --quality 85
python scripts/vips_tool.py thumbnail input.jpg thumb.jpg --size 200
python scripts/vips_tool.py watermark input.jpg output.jpg --text "Copyright 2024"
```

## Supported Formats

| Format | Read | Write | Notes |
|--------|------|-------|-------|
| JPEG | Yes | Yes | Quality 1-100 |
| PNG | Yes | Yes | Compression 0-9 |
| WebP | Yes | Yes | Lossy/lossless |
| AVIF | Yes | Yes | Modern, high compression |
| HEIC | Yes | Yes | Apple format |
| TIFF | Yes | Yes | Multi-page support |
| GIF | Yes | Yes | Animated support |
| PDF | Yes | Yes | Via poppler |
| SVG | Yes | No | Via librsvg |
| RAW | Yes | No | Via libraw |

## Operations

### 1) Resize

Resize images with various fit modes.

```bash
# Resize to exact width, maintain aspect ratio
python scripts/vips_tool.py resize input.jpg output.jpg --width 800

# Resize to exact height
python scripts/vips_tool.py resize input.jpg output.jpg --height 600

# Resize to fit within bounds
python scripts/vips_tool.py resize input.jpg output.jpg --width 800 --height 600

# Resize to cover (fill) dimensions
python scripts/vips_tool.py resize input.jpg output.jpg --width 800 --height 600 --mode cover

# Force exact dimensions (may distort)
python scripts/vips_tool.py resize input.jpg output.jpg --width 800 --height 600 --mode force
```

**Resize modes:**
- `fit` (default): Fit within bounds, maintain aspect ratio
- `cover`: Cover bounds, crop excess
- `force`: Force exact dimensions

### 2) Thumbnail

Create optimized thumbnails with smart cropping.

```bash
# Square thumbnail
python scripts/vips_tool.py thumbnail input.jpg thumb.jpg --size 200

# Attention-based smart crop
python scripts/vips_tool.py thumbnail input.jpg thumb.jpg --size 200 --crop attention

# Center crop
python scripts/vips_tool.py thumbnail input.jpg thumb.jpg --size 200 --crop centre
```

**Crop strategies:**
- `none`: No cropping, fit within size
- `centre`: Crop from center
- `attention`: Smart crop focusing on interesting areas
- `entropy`: Crop to maximize entropy

### 3) Convert

Convert between image formats with quality control.

```bash
# JPEG to WebP
python scripts/vips_tool.py convert input.jpg output.webp --quality 85

# PNG to AVIF (modern format, great compression)
python scripts/vips_tool.py convert input.png output.avif --quality 50

# JPEG to PNG (lossless)
python scripts/vips_tool.py convert input.jpg output.png

# With compression level for PNG
python scripts/vips_tool.py convert input.jpg output.png --compression 9
```

### 4) Crop

Extract a region from an image.

```bash
# Crop 400x300 region starting at (100, 50)
python scripts/vips_tool.py crop input.jpg output.jpg --left 100 --top 50 --width 400 --height 300

# Smart crop to aspect ratio
python scripts/vips_tool.py crop input.jpg output.jpg --width 800 --height 600 --smart
```

### 5) Rotate

Rotate images by any angle.

```bash
# Rotate 90 degrees clockwise
python scripts/vips_tool.py rotate input.jpg output.jpg --angle 90

# Rotate 45 degrees with background color
python scripts/vips_tool.py rotate input.jpg output.jpg --angle 45 --background "255,255,255"

# Auto-rotate based on EXIF
python scripts/vips_tool.py rotate input.jpg output.jpg --auto
```

### 6) Watermark

Add text or image watermarks.

```bash
# Text watermark
python scripts/vips_tool.py watermark input.jpg output.jpg --text "Copyright 2024"

# Position: top-left, top-right, bottom-left, bottom-right, center
python scripts/vips_tool.py watermark input.jpg output.jpg --text "Logo" --position bottom-right

# With opacity
python scripts/vips_tool.py watermark input.jpg output.jpg --text "Draft" --opacity 0.3

# Image watermark
python scripts/vips_tool.py watermark input.jpg output.jpg --image logo.png --position bottom-right --opacity 0.5
```

### 7) Composite

Combine multiple images.

```bash
# Overlay image on background
python scripts/vips_tool.py composite background.jpg overlay.png output.jpg

# With position offset
python scripts/vips_tool.py composite background.jpg overlay.png output.jpg --x 100 --y 50

# With blend mode
python scripts/vips_tool.py composite background.jpg overlay.png output.jpg --blend multiply
```

**Blend modes:** `over`, `multiply`, `screen`, `overlay`, `darken`, `lighten`

### 8) Adjust

Adjust brightness, contrast, saturation.

```bash
# Increase brightness
python scripts/vips_tool.py adjust input.jpg output.jpg --brightness 1.2

# Increase contrast
python scripts/vips_tool.py adjust input.jpg output.jpg --contrast 1.3

# Increase saturation
python scripts/vips_tool.py adjust input.jpg output.jpg --saturation 1.5

# Combine adjustments
python scripts/vips_tool.py adjust input.jpg output.jpg --brightness 1.1 --contrast 1.2 --saturation 1.1
```

### 9) Sharpen

Apply sharpening filter.

```bash
# Default sharpen
python scripts/vips_tool.py sharpen input.jpg output.jpg

# Custom sigma (blur radius)
python scripts/vips_tool.py sharpen input.jpg output.jpg --sigma 1.5

# Custom parameters
python scripts/vips_tool.py sharpen input.jpg output.jpg --sigma 1.5 --x1 2 --m2 3
```

### 10) Blur

Apply Gaussian blur.

```bash
# Default blur
python scripts/vips_tool.py blur input.jpg output.jpg

# Custom sigma
python scripts/vips_tool.py blur input.jpg output.jpg --sigma 5
```

### 11) Flip & Mirror

Flip images horizontally or vertically.

```bash
# Horizontal flip (mirror)
python scripts/vips_tool.py flip input.jpg output.jpg --horizontal

# Vertical flip
python scripts/vips_tool.py flip input.jpg output.jpg --vertical
```

### 12) Grayscale

Convert to grayscale.

```bash
python scripts/vips_tool.py grayscale input.jpg output.jpg
```

### 13) Info

Get image metadata.

```bash
python scripts/vips_tool.py info input.jpg
```

Output:
```
File: input.jpg
Format: jpeg
Width: 3840
Height: 2160
Bands: 3
Interpretation: srgb
Size: 2.4 MB
```

## Batch Processing

Process multiple images at once.

```bash
# Resize all JPEGs in a directory
python scripts/vips_batch.py resize ./input ./output --width 800 --pattern "*.jpg"

# Convert all images to WebP
python scripts/vips_batch.py convert ./input ./output --format webp --quality 85

# Create thumbnails for all images
python scripts/vips_batch.py thumbnail ./input ./thumbnails --size 200

# Custom batch with JSON config
python scripts/vips_batch.py --config batch_config.json
```

### Batch Config Format

```json
{
  "input_dir": "./input",
  "output_dir": "./output",
  "operations": [
    {"type": "resize", "width": 1920},
    {"type": "sharpen", "sigma": 0.5},
    {"type": "convert", "format": "webp", "quality": 85}
  ],
  "pattern": "*.{jpg,jpeg,png}",
  "recursive": true,
  "workers": 4
}
```

## Python API

### Basic Usage

```python
import pyvips

# Load image
image = pyvips.Image.new_from_file("input.jpg")

# Resize
resized = image.resize(0.5)  # 50% scale
resized = image.thumbnail_image(800)  # 800px width

# Save
resized.write_to_file("output.jpg", Q=85)  # JPEG quality 85
resized.write_to_file("output.webp", Q=85)  # WebP quality 85
```

### Chaining Operations

```python
import pyvips

# Load, process, save in one pipeline
image = pyvips.Image.new_from_file("input.jpg", access="sequential")
result = (
    image
    .thumbnail_image(1200)
    .sharpen(sigma=0.5)
    .write_to_file("output.webp", Q=85)
)
```

### Watermark with Text

```python
import pyvips

image = pyvips.Image.new_from_file("input.jpg")

# Create text overlay
text = pyvips.Image.text(
    "Copyright 2024",
    font="sans 24",
    rgba=True
)

# Composite at bottom-right
x = image.width - text.width - 20
y = image.height - text.height - 20
result = image.composite2(text, "over", x=x, y=y)
result.write_to_file("output.jpg")
```

### Batch Processing

```python
import pyvips
from pathlib import Path
from concurrent.futures import ThreadPoolExecutor

def process_image(input_path, output_dir, width=800):
    image = pyvips.Image.new_from_file(str(input_path), access="sequential")
    thumbnail = image.thumbnail_image(width)
    output_path = output_dir / f"{input_path.stem}.webp"
    thumbnail.write_to_file(str(output_path), Q=85)
    return output_path

input_dir = Path("./input")
output_dir = Path("./output")
output_dir.mkdir(exist_ok=True)

files = list(input_dir.glob("*.jpg"))
with ThreadPoolExecutor(max_workers=4) as executor:
    results = executor.map(lambda f: process_image(f, output_dir), files)
```

## CLI Parameters

| Parameter | Description | Default |
|-----------|-------------|---------|
| `--width` | Target width in pixels | - |
| `--height` | Target height in pixels | - |
| `--size` | Thumbnail size (square) | 200 |
| `--quality` | Output quality (1-100) | 85 |
| `--compression` | PNG compression (0-9) | 6 |
| `--mode` | Resize mode: fit, cover, force | fit |
| `--crop` | Crop strategy | none |
| `--angle` | Rotation angle in degrees | 0 |
| `--sigma` | Blur/sharpen radius | 1.0 |
| `--opacity` | Watermark opacity (0-1) | 0.5 |
| `--position` | Watermark position | bottom-right |
| `--workers` | Batch processing threads | 4 |
| `--pattern` | File glob pattern | *.* |
| `--recursive` | Process subdirectories | false |

## Performance Tips

| Tip | Description |
|-----|-------------|
| Sequential access | Use `access="sequential"` for streaming |
| Pipeline operations | Chain operations before writing |
| Parallel processing | Use `ThreadPoolExecutor` for batches |
| Format selection | WebP/AVIF for web, JPEG for photos |
| Quality settings | 85 for quality, 75 for size |
| Thumbnail vs resize | `thumbnail_image` is faster for downscaling |

## Memory Usage

libvips uses a streaming architecture:
- Only loads pixels when needed
- Processes images in small chunks
- Memory usage independent of image size
- 10-100x less memory than ImageMagick/PIL for large images

## Troubleshooting

### Common Issues

| Issue | Solution |
|-------|----------|
| "Cannot find libvips" | Install via brew/apt, check PATH |
| Slow processing | Use sequential access, check disk I/O |
| Memory errors | Increase cache, reduce workers |
| Format not supported | Install optional dependencies |
| Poor quality | Increase quality parameter |
| HEIC not working | Install libheif: `brew install libheif` |
| SVG not rendering | Install librsvg: `brew install librsvg` |

### Windows-Specific Issues

| Issue | Solution |
|-------|----------|
| "cannot load library 'libvips-42.dll'" | Add vips `bin\` folder to PATH |
| DLL not found after install | Restart terminal/PowerShell |
| winget install fails | Use manual download or scoop |
| Permission denied | Run PowerShell as Administrator |
| PATH not updated | Log out and log back in, or restart |

**Windows PATH Setup (Manual):**
```powershell
# Add to current session
$env:PATH = "C:\vips\bin;$env:PATH"

# Add permanently (run as Admin or for current user)
[Environment]::SetEnvironmentVariable("PATH", "C:\vips\bin;$env:PATH", "User")
```

### macOS-Specific Issues

| Issue | Solution |
|-------|----------|
| "cannot load library 'libvips.42.dylib'" | Use `./scripts/run.sh` wrapper |
| DYLD_LIBRARY_PATH not working | macOS SIP blocks env vars; use run.sh |
| Homebrew Python issues | Use `/opt/homebrew/bin/python3` directly |

**macOS Library Path Setup:**
```bash
# Add to ~/.zshrc or ~/.bashrc
export DYLD_LIBRARY_PATH="/opt/homebrew/lib:$DYLD_LIBRARY_PATH"
```

### Linux-Specific Issues

| Issue | Solution |
|-------|----------|
| Package not found | Check distro-specific package name |
| ldconfig issues | Run `sudo ldconfig` after install |
| Permission denied | Use `sudo` for system packages |