Install & Compatibility
Where this runs
tested against v1.4.6 · 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.940 runs
build_error
glibcpy 3.10–3.940 runs
installs and imports cleanly · install 2.4s · import 0.135s · 48MB
46MB installed
● package 46MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
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.
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}'")
Debug
Known issues
breakingPython 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.fixUpgrade Python environment to 3.10 or later.
affects: >=1.3.0
gotchaOpenSlide 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.fixEnsure 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.
affects: All versions
gotchaOn 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`.fixBefore `import openslide`, add `os.add_dll_directory(r'C:\path\to\openslide-win64\bin')` (replace with your actual path to the OpenSlide binaries).
affects: All versions on Windows
gotchaMixing 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.fixStandardize 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`.
affects: All versions
Upgrade
Version history
1.4.6latest on PyPI · released Jun 8, 2026
Audit
Dependencies
PillowrequiredRequired for image manipulation and thumbnail generation.
opensliderequiredThe core C library for reading whole-slide images. The 'openslide-bin' package provides pre-compiled binaries for convenience.