OpenSlide Binary Distribution for Python

Common errors

• ModuleNotFoundError: No module named 'openslide'

  cause The `openslide-python` package, which provides the `openslide` module, is not installed or not accessible in the current Python environment.
  fix Install the Python bindings: `pip install openslide-python`. Remember that `openslide-bin` provides the C library, not the Python module itself.

• OSError: cannot find OpenSlide library
  OR
  WindowsError: [Error 126] The specified module could not be found
  OR
  OSError: dlopen(libopenslide.0.dylib, 6): image not found

  cause The `openslide-python` bindings are installed, but the underlying native OpenSlide C library (provided by `openslide-bin` or system-wide installation) cannot be found or loaded by Python.
  fix Ensure `openslide-bin` is installed: `pip install openslide-bin`. On Windows, if this doesn't resolve it, try adding the path to the `openslide-bin`'s `bin` directory to your system's PATH environment variable or use `os.add_dll_directory()` in your Python script before importing `openslide`.

• openslide.OpenSlideUnsupportedFormatError: file not a OpenSlide compatible whole slide image

  cause The provided image file is either corrupt, not a recognized whole-slide image format, or OpenSlide does not have support for that specific variant.
  fix Verify the file path is correct and the file is a valid, supported WSI format (e.g., .svs, .ndpi, .scn). Check `openslide.OpenSlide.detect_format(filepath)` to see if OpenSlide recognizes the format. Ensure OpenSlide itself is installed correctly and not a minimal build missing codecs.

Warnings

• breaking Python 3.8 support was dropped in openslide-bin v4.0.0.10. Ensure your Python environment is 3.9 or newer.
  Fix: Upgrade your Python environment to 3.9 or higher. (e.g., `conda create -n openslide_env python=3.9` or `pyenv install 3.9.x`)
• gotcha Users often confuse `openslide-bin` and `openslide-python`. `openslide-bin` provides the *native C library* binaries, while `openslide-python` provides the *Python bindings* to use that library. Both are typically required for Python development.
  Fix: Always install both `openslide-bin` and `openslide-python` via pip (e.g., `pip install openslide-bin openslide-python`). The Python code will then `import openslide`.
• gotcha On Windows, 'DLL load failed' or 'cannot find OpenSlide library' errors can occur due to conflicting DLLs in the system PATH or the OpenSlide binaries not being discoverable by `openslide-python`.
  Fix: Ensure `openslide-bin` is installed. If issues persist, manually add the `bin` directory of your OpenSlide installation (e.g., `site-packages/openslide/openslide-win64-XXXX/bin`) to the system PATH environment variable, or use `os.add_dll_directory()` in your Python code before `import openslide`.
• gotcha Mixing installation methods for OpenSlide (e.g., `pip` for `openslide-python` and a system package manager like `apt`, `brew`, or `conda` for the OpenSlide C library) can lead to library conflicts and runtime errors.
  Fix: For Python-only use, the recommended approach is to install both `openslide-bin` and `openslide-python` using `pip`. If using a package manager like `conda`, install both via `conda` from the same channel (e.g., `conda install openslide-python openslide -c conda-forge`). Avoid mixing methods.

Install

• pip install openslide-bin openslide-python Recommended Installation
• pip install openslide-bin Install OpenSlide binaries only

Imports

• OpenSlide
  wrong:

  import openslide-bin

  correct:

  import openslide

  The `openslide-bin` package provides the native library, not Python modules directly. Python bindings are in `openslide-python` which is imported as `openslide`.

Quickstart

This quickstart demonstrates how to open a whole-slide image using `openslide-python` (which leverages the `openslide-bin` installed native library), extract its properties, generate a thumbnail, and read a specific region. Ensure you have a valid WSI file (e.g., .svs) to test.

import os
import openslide
from PIL import Image

# NOTE: For Windows, if you encounter 'DLL load failed' or 'cannot find OpenSlide library',
# you might need to manually specify the path to the openslide-bin 'bin' directory.
# Example: openslide_bin_path = os.path.join(os.path.dirname(os.path.abspath(__file__)), 'openslide-win64-20231011', 'bin')
# if os.name == 'nt':
#     os.add_dll_directory(openslide_bin_path)

# Placeholder for a whole-slide image file. Replace with your .svs, .ndpi, etc.
# You can download sample slides from openslide.org/demo
slide_path = os.environ.get('OPENSLIDE_SAMPLE_SLIDE_PATH', 'path/to/your/slide.svs')

try:
    with openslide.OpenSlide(slide_path) as slide:
        print(f"Opened slide: {slide_path}")
        print(f"Dimensions (level 0): {slide.dimensions}")
        print(f"Level count: {slide.level_count}")
        print(f"Properties: {slide.properties.keys()}")

        # Get a thumbnail of the slide
        thumbnail = slide.get_thumbnail((500, 500))
        thumbnail.save('slide_thumbnail.png')
        print("Saved thumbnail to slide_thumbnail.png")

        # Read a region from a specific level
        # For example, read a 256x256 region from the highest resolution (level 0)
        # starting at (0, 0) pixel coordinates.
        region_image = slide.read_region((0, 0), 0, (256, 256))
        region_image.save('slide_region_level0.png')
        print("Saved a 256x256 region from level 0 to slide_region_level0.png")

except openslide.OpenSlideError as e:
    print(f"Error opening slide: {e}")
    print("Please ensure the slide path is correct and the file is a supported OpenSlide format.")
except FileNotFoundError:
    print(f"Error: Slide file not found at {slide_path}")
except Exception as e:
    print(f"An unexpected error occurred: {e}")