OpenSlide Python

1.4.3 · active · verified Thu Apr 16

OpenSlide Python provides a Python interface to the OpenSlide C library, which is designed for reading high-resolution whole-slide images (WSI) commonly used in digital pathology. These images, often gigapixels in size, are too large for standard image processing libraries, so OpenSlide offers efficient multi-resolution access. The current version is 1.4.3, and the project maintains a regular release cadence with frequent updates.

Common errors

```
ImportError: DLL load failed while importing _lowlevel: The specified module could not be found.
```
cause The underlying OpenSlide C library or its dependencies are not found in the system's PATH or DLL search paths on Windows.

fix 1. Ensure the OpenSlide C library is installed, preferably via `pip install openslide-bin`. 2. If manually installed, add the directory containing `openslide.dll` (and other DLLs) to the system's PATH environment variable or dynamically using `os.add_dll_directory()` in Python before importing `openslide`.
```
ImportError: Couldn't locate OpenSlide dylib
```
cause The OpenSlide C library (`.dylib` on macOS, `.so` on Linux) cannot be found in standard library search paths.

fix 1. Ensure the OpenSlide C library is installed, preferably via `pip install openslide-bin`. 2. If manually installed, ensure the library is in a standard system path (e.g., `/usr/local/lib`) or added to `LD_LIBRARY_PATH` (Linux) / `DYLD_LIBRARY_PATH` (macOS).
```
openslide.OpenSlideUnsupportedFormatError: Unsupported or corrupt file
```
cause The file provided to `openslide.OpenSlide()` is either not a supported whole-slide image format or is corrupted.

fix Verify the file is a valid whole-slide image (e.g., .svs, .ndpi, .dcm) and not corrupted. Check OpenSlide's supported formats. Try opening a known-good sample slide.

Warnings

breaking Python 3.9 support was dropped in openslide-python 1.4.3, 3.8 in 1.4.2, and 3.7 in 1.3.0. Users must upgrade to Python 3.10 or newer.
Fix: Upgrade Python environment to 3.10 or later.
gotcha OpenSlide Python is a wrapper for the OpenSlide C library, which must be installed separately. While `pip install openslide-bin` simplifies this, it may not cover all platforms or complex system setups. Failure to install the C library will lead to import errors.
Fix: Ensure the OpenSlide C library is installed. Use `pip install openslide-bin` or install via your system's package manager (e.g., `apt`, `dnf`, `macports`, `conda`). Refer to the official OpenSlide documentation for detailed installation instructions for your OS.
gotcha On Windows, if the OpenSlide C library DLLs are not found in standard system paths or provided by `openslide-bin`, you may need to explicitly add their directory to the DLL search path using `os.add_dll_directory()` before importing `openslide`.
Fix: Before `import openslide`, add `os.add_dll_directory(r'C:\path\to\openslide-win64\bin')` (replace with your actual path to the OpenSlide binaries).
gotcha Mixing OpenSlide (C library) and OpenSlide Python installations from different package managers (e.g., OpenSlide from MacPorts and OpenSlide Python from Anaconda) can lead to library conflicts and unexpected behavior.
Fix: Standardize on a single installation method. For example, use `pip install openslide-python openslide-bin` for both, or install both through a single system package manager like `conda`.

Install

pip install openslide-python openslide-bin Recommended (Python bindings + OpenSlide C library)
pip install openslide-python # If OpenSlide C library is already installed via system package manager Alternative (Python bindings only)

Imports

OpenSlide
```
from openslide import OpenSlide
```
OpenSlideError
```
from openslide import OpenSlideError
```
Base exception for OpenSlide related errors.
OpenSlideUnsupportedFormatError
```
from openslide import OpenSlideUnsupportedFormatError
```
Raised when attempting to open an unsupported or corrupt file.

Quickstart

This quickstart demonstrates how to open a whole-slide image, access its basic properties (dimensions, level count, vendor, objective power), and generate a thumbnail image using the `OpenSlide` object. It includes error handling for common issues like file not found or unsupported formats.

import openslide
from PIL import Image
import os

# NOTE: Replace 'path/to/your/slide.svs' with an actual whole-slide image file.
# You might need to adjust the path if running on Windows and openslide-bin isn't used,
# by adding the OpenSlide DLL directory to os.add_dll_directory().
# Example for Windows (uncomment and modify if needed):
# os.add_dll_directory(r'C:\path\to\OpenSlide\bin')

slide_path = os.environ.get('OPENSLIDE_TEST_SLIDE', 'path/to/your/slide.svs')

try:
    with openslide.OpenSlide(slide_path) as slide:
        print(f"Slide dimensions (level 0): {slide.dimensions}")
        print(f"Number of levels: {slide.level_count}")
        print(f"Vendor: {slide.properties.get(openslide.PROPERTY_NAME_VENDOR, 'Unknown')}")
        print(f"Objective Power: {slide.properties.get(openslide.PROPERTY_NAME_OBJECTIVE_POWER, 'Unknown')}")

        # Get a thumbnail (e.g., max 200x200 pixels)
        thumbnail: Image.Image = slide.get_thumbnail((200, 200))
        # thumbnail.save('thumbnail.png')
        print(f"Generated thumbnail with size: {thumbnail.size}")

        # Read a region at a specific level (e.g., 512x512 pixels at level 2)
        # region: Image.Image = slide.read_region((0, 0), 2, (512, 512))
        # region.save('region_level2.png')

except openslide.OpenSlideError as e:
    print(f"Error opening slide: {e}")
except FileNotFoundError:
    print(f"Error: Slide file not found at '{slide_path}'")

view raw JSON →