pyvips Documentation

Unlike many image libraries, pyvips does not manipulate images directly in memory. Instead, it builds a pipeline of operations.

When the end of the pipeline is connected to a destination (like a file write), the entire pipeline executes at once. The image is streamed in parallel from source to destination one section at a time. This approach makes pyvips extremely fast and memory-efficient, as it avoids loading entire large images into memory.

The pyvips.enums module provides Python classes representing various libvips enumerations.

In pyvips, enum values are passed to API methods as strings. The enum classes serve as a source of truth for these valid string values, helping to prevent typos and providing discoverability via IDE autocompletion.

Instead of manually typing strings like 'bilinear' or 'lanczos3', you should use the corresponding attribute from the enum classes in pyvips.enums.

Paint operations such as Image.draw_circle and Image.draw_line modify their input image in-place. Because libvips is typically lazy and functional, these operations can cause crashes if not handled carefully.

To prevent crashes, the pyvips wrapper automatically creates a private in-memory copy of the image before executing a drawing operation.

Performance Note: This automatic copying makes drawing operations inefficient. If you perform many drawing operations (e.g., drawing 100 lines), the wrapper will perform 100 copies. While the wrapper attempts to recycle memory, this is still significantly slower than standard libvips operations. To avoid this overhead, you must call the underlying drawing operations yourself via the C API or equivalent low-level methods.

Some libvips operators use enums to select an action (e.g., vips_math with a 'sin' argument). pyvips automatically expands these enums into dedicated method names for convenience.

Instead of: image.math('sin')

You can use: image.sin()

pyvips uses __getattr__ to allow accessing libvips properties and operations directly as attributes.

Reading Metadata

Use image.get(key) to retrieve metadata. You can use image.get_fields() to see all available field names.

Modifying Metadata

Because libvips caches and shares images, you cannot modify an image in place. To change metadata, you must first create a private copy using .copy().

# Get metadata
exif_date = image.get('exif-ifd0-DateTime')

# Set metadata (must copy first)
new_image = image.copy().set('icc-profile-data', new_profile)

On Windows, if you do not want to add the libvips bin directory to your system PATH, you can configure it programmatically at the start of your application. This is necessary for pyvips to find the required DLLs.

For Python 3.8 and later, use os.add_dll_directory.

import os
vipsbin = r'c:\vips-dev-8.16\bin'
add_dll_dir = getattr(os, 'add_dll_directory', None)
if callable(add_dll_dir):
    add_dll_dir(vipsbin)
else:
    os.environ['PATH'] = os.pathsep.join((vipsbin, os.environ['PATH']))

import pyvips

The quickest way to start is by installing the self-contained binary package. This includes the most commonly needed libraries and works on most platforms (Linux, Windows, macOS) across 64/32-bit x64 and ARM CPUs.

Note: The binary version is missing certain features like PDF loading and OpenSlide support.

$ pip install "pyvips[binary]"

pyvips provides type hints via PEP 561 type stub files (pyvips/__init__.pyi). To use them, install mypy and pyvips, then run mypy on your script.

Note: pyvips methods accept arbitrary keyword arguments for libvips options which may not be fully covered by the type hints.

$ pip install mypy pyvips
$ mypy your_script.py

pyvips integrates easily with NumPy and PIL for data exchange.

pyvips to NumPy/PIL

• Use image.numpy() or numpy.asarray(image) to convert a pyvips image to a NumPy array.
• Use image.pil() to convert a pyvips image to a PIL image.

NumPy/PIL to pyvips

• Use pyvips.Image.new_from_array(array) to create an image from a NumPy array or a PIL image.

import pyvips
import numpy as np
import PIL.Image

# NumPy to pyvips
a = (np.random.random((100, 100, 3)) * 255).astype(np.uint8)
image = pyvips.Image.new_from_array(a)

# PIL to pyvips
pil_image = PIL.Image.new('RGB', (60, 30), color='red')
image = pyvips.Image.new_from_array(pil_image)

# pyvips to NumPy
array = image.numpy()

# pyvips to PIL
pil_img = image.pil()

Instead of loading directly from files, you can use pyvips.Source and pyvips.Target to manage image input and output. This allows you to work with files, descriptors (like pipes), or memory areas.

• Use pyvips.Source.new_from_file(path) to create a source.
• Use pyvips.Target.new_to_file(path) to create a target.
• Use pyvips.Image.new_from_source(source, name, access=...) to create an image from a source.
• Use image.write_to_target(target, extension) to write an image to a target.

source = pyvips.Source.new_from_file("some/file/name")
image = pyvips.Image.new_from_source(source, "", access="sequential")
target = pyvips.Target.new_to_file("some/file/name")
image.write_to_target(target, ".png")