vips-rs

English | Chinese Simplified

Rust bindings for libvips: fast, low-memory image processing with a safe, ergonomic API.

• Safe wrappers over common libvips APIs
• Process-wide initialization and RAII image ownership
• Practical helpers for reading, transforming, and writing images
• Lazy pipeline evaluation (libvips demand-driven processing)

Documentation: https://docs.rs/vips/

Requirements

• Current stable Rust (edition 2024)
• libvips installed on your system
  • macOS: brew install vips
  • Linux: apt-get install -y pkg-config libvips-dev (or your distro equivalent)

Installation

Add to your Cargo.toml:

[dependencies]
vips = "0.2"

Quick start

use vips::*;

fn main() -> Result<()> {
    // Initialize once per process. The boolean enables leak diagnostics.
    let _instance = VipsInstance::new("app_example", true)?;

    // Create a thumbnail with forced width and height (preferred for files)
    let thumb = VipsImage::thumbnail_file("./examples/images/kodim01.png", 320, 240, VipsSize::VIPS_SIZE_FORCE)?;

    // Save the result
    thumb.write_to_file("kodim01_320x240.jpg")?;
    Ok(())
}

0.2.0 additions and migration

This version uses the published vips-sys 0.3.0 dependency; no sibling checkout is required.

• write_to_memory_owned / write_to_buffer_owned return VipsOwnedBuffer, which owns a GLib allocation and exposes immutable bytes without the extra full-buffer copy into a Rust Vec. Existing Vec APIs remain available.
• from_file_with_access / from_buffer_with_access accept a VipsAccess hint. Prefer sequential access for a one-pass pipeline and file/buffer thumbnail constructors for shrink-on-load.
• --features v8_18 adds tile_size, gainmap, camera RAW file/buffer loaders, UltraHDR file/buffer IO and scRGB conversion, Oklab/Oklch conversion helpers, and interpretation_bands. Requires libvips 8.18+; RAW and HDR codecs remain optional build-time dependencies of the system library.
• VipsRegion now has a buffer lifetime; lazy multi-image operations retain every input buffer's lifetime. Image handles may drop before their results, but borrowed pixel buffers must remain alive.
• Drawing detaches borrowed/shared storage into writable memory on first use. Borrowed memory must be correctly aligned for its sample format.
• VipsInterpolateMethod::call is unsafe because output size/alignment and a prepared interpolation window are native caller obligations.
• VipsInstance uses the same initialization state as init and no longer shuts the process-wide library down when its handle is dropped.

vips = { version = "0.2", features = ["v8_18"] }

Run cargo run --release --example buffer_bench for an alternating ABBA comparison of copied and owned raw exports. See the review and roadmap.

Working with memory

• Own the pixel buffer (simple and recommended):

let pixels = vec![0u8; 256 * 256 * 3]; // RGB
let img = VipsImage::from_memory(pixels, 256, 256, 3, VipsBandFormat::VIPS_FORMAT_UCHAR)?;
let thumb = img.thumbnail(200, 200, VipsSize::VIPS_SIZE_FORCE)?;
thumb.write_to_file("black_200x200.png")?;

• Borrow a pixel buffer (make sure the backing data outlives all derived images):

let pixels = vec![0u8; 256 * 256 * 3];
let img = VipsImage::from_memory_reference(&pixels, 256, 256, 3, VipsBandFormat::VIPS_FORMAT_UCHAR)?;
let thumb = img.thumbnail(200, 200, VipsSize::VIPS_SIZE_FORCE)?;
thumb.write_to_file("black_ref_200x200.png")?;

Lifetimes and common pitfalls

• Prefer owned constructors (from_file, from_memory) when possible.
• Borrowing constructors (from_memory_reference) tie the image lifetime to the borrowed slice. Do not let the slice drop before all derived images are fully used.
• Native image references are retained by derived pipelines; creator handles may drop earlier. Every borrowed input buffer must still outlive the result.

API highlights

Performance tips

• Prefer VipsImage::thumbnail_file / VipsImage::thumbnail_buffer over from_file/from_buffer + thumbnail for downscales. They call vips_thumbnail / vips_thumbnail_buffer, which combine load and resize so libvips can shrink-on-load (often ~3× faster and several times lower peak memory than thumbnail_image). Use the instance method thumbnail only for already-decoded raw pixels.
• Prefer write_to_file over write_to_memory when the destination is a path (avoids a full in-memory copy).
• For already-decoded large images, benchmark resize_reduce against resize before choosing the extra box pre-shrink pass; it can be slower on small inputs.
• Tune vips::set_concurrency, set_max_operations, and set_max_mem_bytes for your workload.
• libvips pipelines are lazy: operations enqueue work until the image is written or materialized.

Notes

• Initialization: init and VipsInstance share process-wide state. Native objects use RAII; global state remains available until process exit.
• Side effects: most operations return new images; drawing operations modify self.
• If a higher-level wrapper is missing, you can still access lower-level bindings in vips-sys or use unsafe vips::vips_call(...) to invoke libvips operations directly.

Local development

Builds resolve vips-sys from crates.io. To develop both crates together, add this optional override at the workspace/consumer root:

[patch.crates-io]
vips-sys = { path = "../vips-sys" }

Docker-based check (no local libvips required):

docker run --rm -v "$PWD/..":/workspace -w /workspace/vips-rs rust:1.88-bookworm \
  bash -c 'apt-get update -qq && apt-get install -y -qq pkg-config libvips-dev && cargo test'

License

MIT

Changelog

See CHANGELOG.md.