Install & Compatibility
Where this runs
tested against v3.2.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 0.000s · 38MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 4.1s · import 0.050s · 38MB
36MB installed
● package 36MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
pyvips
✓ import pyvips
✗ import pyvips
This example loads an image, resizes it to 50% of its original dimensions, converts it to grayscale, and then saves it as a PNG file. It demonstrates the basic `new_from_file`, chained operations, and `write_to_file` methods. A dummy 'input.jpg' is created if not found for immediate execution.
import pyvips
import os
# Assuming 'input.jpg' exists in the current directory
# For demonstration, let's create a dummy image if not present
if not os.path.exists('input.jpg'):
# In a real scenario, you'd have an actual image file.
# For this quickstart, we'll create a simple black image.
dummy_image = pyvips.Image.black(100, 100, bands=3)
dummy_image.write_to_file('input.jpg')
# Load an image
image = pyvips.Image.new_from_file('input.jpg')
# Perform an operation, e.g., resize to 50% and convert to grayscale
processed_image = image.resize(0.5).colourspace('b-w')
# Save the processed image
processed_image.write_to_file('output_grayscale.png')
print(f"Processed image saved to output_grayscale.png (width: {processed_image.width}, height: {processed_image.height})")
Debug
Known issues
breakingThe `libvips` shared library is a mandatory external dependency. If not installed on your system, `pyvips` will fail to import with an `OSError` or `ModuleNotFoundError` for `_libvips`.fixInstall `libvips` system-wide (e.g., `apt install libvips-dev` on Debian/Ubuntu, `brew install vips` on macOS). On Windows, download a pre-compiled binary and add its `bin` directory to your system's `PATH` environment variable, or use `pip install "pyvips[binary]"` for a self-contained (but feature-limited) installation.
affects: All versions
gotchaUsing `pip install "pyvips[binary]"` installs a self-contained `libvips` binary that may lack support for certain features like PDF loading, OpenSlide (for whole-slide images), or specific image formats. If you need these, a system-wide installation of `libvips` with full feature support is necessary.fixFor full `libvips` features, install `libvips` separately through your system's package manager or from source, ensuring it includes desired optional dependencies, and then install `pyvips` without the `[binary]` extra (`pip install pyvips`).
affects: All versions
breakingSince `libvips` version 8.9, modifying metadata on 'shared' images (those with a reference count greater than one) is blocked to prevent race conditions. Attempts to do so will be ignored or raise a warning.fixAlways call `.copy()` on an `Image` object before attempting to modify its metadata if there's a possibility it's being shared, e.g., `new_image = original_image.copy().set('field', value)`. affects: libvips >= 8.9
gotchaOperations that draw directly onto an image, such as `Image.draw_circle()` or `Image.draw_line()`, inherently modify their input. `pyvips` will make a private copy of the image in memory before performing these operations to prevent crashes. Repeated drawing can thus be inefficient due to multiple memory copies.fixFor complex drawing tasks, consider combining drawing elements into an overlay image and using `image.composite()` or equivalent methods to merge them efficiently, or perform drawing operations on a temporary image if performance is critical.
affects: All versions
gotchaIf `cffi` is unable to build a binary extension for `pyvips` (API mode), it will fall back to ABI mode, which results in approximately 20% slower execution and longer startup times.fixEnsure you have `libvips` development headers and a working C compiler (e.g., build-essential on Linux, Xcode Command Line Tools on macOS) installed before running `pip install pyvips`. If issues persist, try `pip install --no-cache-dir pyvips` to force a clean build attempt.
affects: All versions
gotchaWhen processing extremely large images, errors like 'arithmetic overflow' can occur, often stemming from underlying `libvips` components (e.g., `libpng`) if a 32-bit `libvips` build is in use. This limits the maximum image size that can be handled.fixEnsure you are using a 64-bit Python installation and a 64-bit build of `libvips`. Verify `libvips` was compiled with support for large file sizes if you frequently encounter such issues.
affects: All versions, particularly with 32-bit `libvips` builds
Upgrade
Version history
3.2.0latest on PyPI · released Aug 29, 2026
Audit
Dependencies
libvipsrequiredCore image processing library (external C library), version 8.2+ required, 8.9+ for full features.
cffirequiredPython FFI binding for libvips.