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)

CODEBLOCK0

The install script will:

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

Manual Install

macOS (Homebrew):
CODEBLOCK1

Ubuntu/Debian:
CODEBLOCK2

Fedora/RHEL:
CODEBLOCK3

Arch Linux:
CODEBLOCK4

Windows (PowerShell, recommended):
CODEBLOCK5

Windows (Manual):
CODEBLOCK6

Install uv (if not installed):
CODEBLOCK7

Basic Usage

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

Windows - Using run.bat wrapper (recommended):
CODEBLOCK9

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

Direct Python (if library paths are configured):
CODEBLOCK11

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.

CODEBLOCK12

Resize modes:

- fit (default): Fit within bounds, maintain aspect ratio
INLINECODE2: Cover bounds, crop excess
INLINECODE3: Force exact dimensions

2) Thumbnail

Create optimized thumbnails with smart cropping.

CODEBLOCK13

Crop strategies:

- none: No cropping, fit within size
INLINECODE5: Crop from center
INLINECODE6: Smart crop focusing on interesting areas
INLINECODE7: Crop to maximize entropy

3) Convert

Convert between image formats with quality control.

CODEBLOCK14

4) Crop

Extract a region from an image.

CODEBLOCK15

5) Rotate

Rotate images by any angle.

CODEBLOCK16

6) Watermark

Add text or image watermarks.

CODEBLOCK17

7) Composite

Combine multiple images.

CODEBLOCK18

Blend modes: over, multiply, screen, overlay, darken, INLINECODE13

8) Adjust

Adjust brightness, contrast, saturation.

CODEBLOCK19

9) Sharpen

Apply sharpening filter.

CODEBLOCK20

10) Blur

Apply Gaussian blur.

CODEBLOCK21

11) Flip & Mirror

Flip images horizontally or vertically.

CODEBLOCK22

12) Grayscale

Convert to grayscale.

CODEBLOCK23

13) Info

Get image metadata.

CODEBLOCK24

Output:
CODEBLOCK25

Batch Processing

Process multiple images at once.

CODEBLOCK26

Batch Config Format

CODEBLOCK27

Python API

Basic Usage

CODEBLOCK28

Chaining Operations

CODEBLOCK29

Watermark with Text

CODEBLOCK30

Batch Processing

CODEBLOCK31

CLI Parameters

Parameter	Description	Default
INLINECODE14	Target width in pixels	-
INLINECODE15

Performance Tips

Tip	Description
Sequential access	Use `access="sequential"` for streaming
Pipeline operations

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

Windows-Specific Issues

Issue	Solution
"cannot load library 'libvips-42.dll'"	Add vips `bin\` folder to PATH
DLL not found after install

Windows PATH Setup (Manual):
CODEBLOCK32

macOS-Specific Issues

Issue	Solution
"cannot load library 'libvips.42.dylib'"	Use `./scripts/run.sh` wrapper
DYLDLIBRARYPATH not working

macOS SIP blocks env vars; use run.sh | | Homebrew Python issues | Use /opt/homebrew/bin/python3 directly |

macOS Library Path Setup:
CODEBLOCK33

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 |

libvips 图像处理

使用 pyvips 调用 libvips 实现快速、内存高效的图像处理。支持 300 多种操作，包括调整大小、裁剪、旋转、格式转换、水印、合成等。非常适合批量处理大尺寸图像。

适用场景

- 高效调整图像大小、裁剪或生成缩略图
格式转换（JPEG、PNG、WebP、AVIF、HEIC、TIFF、PDF、SVG）
添加水印或文字叠加
批量处理多张图像
低内存占用处理大尺寸图像
创建面向网页优化的图像处理流水线

快速开始

一键安装

bash

或：pip install pyvips

Ubuntu/Debian：
bash
sudo apt-get install libvips-dev
uv pip install pyvips # 推荐

或：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，推荐）：
powershell

一键安装（下载 libvips + 安装 pyvips）

.\scripts\install.ps1

Windows（手动）：
powershell

方式 1：winget（如果可用）

winget install libvips.libvips

方式 2：scoop

scoop install libvips

方式 3：手动下载

从 https://github.com/libvips/libvips/releases 下载

解压到 C:\vips 或 %LOCALAPPDATA%\vips

将 bin\ 添加到 PATH

安装 pyvips

uv pip install pyvips

或：pip install pyvips

安装 uv（如果未安装）：
bash

macOS/Linux

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

Windows（PowerShell）

irm https://astral.sh/uv/install.ps1 | iex

基本用法

macOS/Linux - 使用 run.sh 包装器（推荐）：
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 - 使用 run.bat 包装器（推荐）：
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

跨平台 - 使用 uv（执行 uv sync 后）：
bash
uv run python scripts/vips_tool.py resize input.jpg output.jpg --width 800

直接使用 Python（如果库路径已配置）：
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

支持的格式

格式	读取	写入	说明
JPEG	是	是	质量 1-100
PNG

是 | 是 | 压缩 0-9 | | WebP | 是 | 是 | 有损/无损 | | AVIF | 是 | 是 | 现代格式，高压缩率 | | HEIC | 是 | 是 | Apple 格式 | | TIFF | 是 | 是 | 支持多页 | | GIF | 是 | 是 | 支持动画 | | PDF | 是 | 是 | 通过 poppler | | SVG | 是 | 否 | 通过 librsvg | | RAW | 是 | 否 | 通过 libraw |

操作

1）调整大小

使用多种适配模式调整图像大小。

bash

调整到指定宽度，保持宽高比

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

调整到指定高度

python scripts/vips_tool.py resize input.jpg output.jpg --height 600

调整到适合边界内

python scripts/vips_tool.py resize input.jpg output.jpg --width 800 --height 600

调整到覆盖（填充）尺寸

python scripts/vips_tool.py resize input.jpg output.jpg --width 800 --height 600 --mode cover

强制精确尺寸（可能变形）

python scripts/vips_tool.py resize input.jpg output.jpg --width 800 --height 600 --mode force

调整大小模式：

- fit（默认）：适合边界内，保持宽高比
cover：覆盖边界，裁剪多余部分
force：强制精确尺寸

2）缩略图

创建带智能裁剪的优化缩略图。

bash

方形缩略图

python scripts/vips_tool.py thumbnail input.jpg thumb.jpg --size 200

基于注意力的智能裁剪

python scripts/vips_tool.py thumbnail input.jpg thumb.jpg --size 200 --crop attention

中心裁剪

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

裁剪策略：

- none：不裁剪，适合尺寸内
centre：从中心裁剪
attention：智能裁剪，聚焦感兴趣区域
entropy：裁剪以最大化熵值

3）格式转换

在图像格式之间转换，支持质量控制。

bash

JPEG 转 WebP

python scripts/vips_tool.py convert input.jpg output.webp --quality 85

PNG 转 AVIF（现代格式，压缩效果出色）

python scripts/vips_tool.py convert input.png output.avif --quality 50

JPEG 转 PNG（无损）

python scripts/vips_tool.py convert input.jpg output.png

带 PNG 压缩级别

python scripts/vips_tool.py convert input.jpg output.png --compression 9

4）裁剪

从图像中提取一个区域。

bash

从 (100, 50) 开始裁剪 400x300 区域

python scripts/vips_tool.py crop input.jpg output.jpg --left 100 --top 50 --width 400 --height 300

按宽高比智能裁剪

python scripts/vips_tool.py crop input.jpg output.jpg --width 800 --height 600 --smart

5）旋转

按任意角度旋转图像。

bash

顺时针旋转 90 度

python scripts/vips_tool.py rotate input.jpg output.jpg --angle 90

旋转 45 度并设置背景色

python scripts/vips_tool.py rotate input.jpg output.jpg --angle 45 --background 255,255,255

基于 EXIF 自动旋转

python scripts/vips_tool.py rotate input.jpg output.jpg --auto

6）水印

添加文字或图像水印。

bash

文字水印

位置：左上、右上、左下、右下、居中

python scripts/vips_tool.py watermark input.jpg output.jpg --text Logo --position bottom-right

设置不透明度

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

图像水印

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

7）合成

组合多张图像。

bash

在背景上叠加图像

python scripts/vips_tool.py composite background.jpg overlay.png output.jpg

带位置偏移

python scripts/vips_tool.py composite

libvips图像处理

libvips图像处理

libvips Image Processing

When to Use

Quick Start

Install (One-Click)

Manual Install

Basic Usage

Supported Formats

Operations

1) Resize

2) Thumbnail

3) Convert

4) Crop

5) Rotate

6) Watermark

7) Composite

8) Adjust

9) Sharpen

10) Blur

11) Flip & Mirror

12) Grayscale

13) Info

Batch Processing

Batch Config Format

Python API

Basic Usage

Chaining Operations

Watermark with Text

Batch Processing

CLI Parameters

Performance Tips

Memory Usage

Troubleshooting

Common Issues

Windows-Specific Issues

macOS-Specific Issues

Linux-Specific Issues

libvips 图像处理

适用场景

快速开始

一键安装

推荐：自动检测操作系统并安装所有依赖

手动安装

或：pip install pyvips

或：pip install pyvips

一键安装（下载 libvips + 安装 pyvips）

方式 1：winget（如果可用）

方式 2：scoop

方式 3：手动下载

从 https://github.com/libvips/libvips/releases 下载

解压到 C:\vips 或 %LOCALAPPDATA%\vips

将 bin\ 添加到 PATH

安装 pyvips

或：pip install pyvips

macOS/Linux

Windows（PowerShell）

基本用法

支持的格式

操作

1）调整大小

调整到指定宽度，保持宽高比

调整到指定高度

调整到适合边界内

调整到覆盖（填充）尺寸

强制精确尺寸（可能变形）

2）缩略图

方形缩略图

基于注意力的智能裁剪

中心裁剪

3）格式转换

JPEG 转 WebP

PNG 转 AVIF（现代格式，压缩效果出色）

JPEG 转 PNG（无损）

带 PNG 压缩级别

4）裁剪

从 (100, 50) 开始裁剪 400x300 区域

按宽高比智能裁剪

5）旋转

顺时针旋转 90 度