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
• RAII-style initialization/shutdown management
• Practical helpers for reading, transforming, and writing images
• Lazy pipeline evaluation (libvips demand-driven processing)

Documentation: https://houseme.github.io/vips-rs/vips/

Requirements

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

Installation

Add to your Cargo.toml:

[dependencies]
vips = "0.1"

Quick start

use vips::*;

fn main() -> Result<()> {
    // Initialize libvips once per process. The boolean usually controls auto-shutdown.
    let _instance = VipsInstance::new("app_example", true)?;

    // Load an image from file
    let img = VipsImage::from_file("./examples/images/kodim01.png")?;

    // Create a thumbnail with forced width and height
    let thumb = img.thumbnail(320, 240, VipsSize::VIPS_SIZE_FORCE)?;

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

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.
• Keep the creator image in scope while using results that reference it. Avoid creating images inside a short inner scope and returning derived results from it.

API highlights

Performance tips

• Prefer write_to_file over write_to_memory when the destination is a path (avoids a full in-memory copy).
• For large downscales (factor ≳ 3 on multi-megapixel sources), prefer resize_reduce — it box-pre-shrinks before the final kernel.
• 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: the crate manages vips_init/vips_shutdown via VipsInstance and standard library primitives ( OnceLock).
• 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 vips::call(...) to invoke libvips operations directly.

Local development

Published builds resolve vips-sys from crates.io. To develop against a sibling checkout, add a [patch] at the workspace/consumer root (or temporarily in this crate):

[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.