{"id":7476,"library":"openslide-python","title":"OpenSlide Python","description":"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.","status":"active","version":"1.4.3","language":"en","source_language":"en","source_url":"https://github.com/openslide/openslide-python","tags":["microscopy","pathology","image processing","WSI","whole-slide-imaging","digital-pathology"],"install":[{"cmd":"pip install openslide-python openslide-bin","lang":"bash","label":"Recommended (Python bindings + OpenSlide C library)"},{"cmd":"pip install openslide-python # If OpenSlide C library is already installed via system package manager","lang":"bash","label":"Alternative (Python bindings only)"}],"dependencies":[{"reason":"Required for image manipulation and thumbnail generation.","package":"Pillow","optional":false},{"reason":"The core C library for reading whole-slide images. The 'openslide-bin' package provides pre-compiled binaries for convenience.","package":"openslide","optional":false}],"imports":[{"symbol":"OpenSlide","correct":"from openslide import OpenSlide"},{"note":"Base exception for OpenSlide related errors.","symbol":"OpenSlideError","correct":"from openslide import OpenSlideError"},{"note":"Raised when attempting to open an unsupported or corrupt file.","symbol":"OpenSlideUnsupportedFormatError","correct":"from openslide import OpenSlideUnsupportedFormatError"}],"quickstart":{"code":"import openslide\nfrom PIL import Image\nimport os\n\n# NOTE: Replace 'path/to/your/slide.svs' with an actual whole-slide image file.\n# You might need to adjust the path if running on Windows and openslide-bin isn't used,\n# by adding the OpenSlide DLL directory to os.add_dll_directory().\n# Example for Windows (uncomment and modify if needed):\n# os.add_dll_directory(r'C:\\path\\to\\OpenSlide\\bin')\n\nslide_path = os.environ.get('OPENSLIDE_TEST_SLIDE', 'path/to/your/slide.svs')\n\ntry:\n    with openslide.OpenSlide(slide_path) as slide:\n        print(f\"Slide dimensions (level 0): {slide.dimensions}\")\n        print(f\"Number of levels: {slide.level_count}\")\n        print(f\"Vendor: {slide.properties.get(openslide.PROPERTY_NAME_VENDOR, 'Unknown')}\")\n        print(f\"Objective Power: {slide.properties.get(openslide.PROPERTY_NAME_OBJECTIVE_POWER, 'Unknown')}\")\n\n        # Get a thumbnail (e.g., max 200x200 pixels)\n        thumbnail: Image.Image = slide.get_thumbnail((200, 200))\n        # thumbnail.save('thumbnail.png')\n        print(f\"Generated thumbnail with size: {thumbnail.size}\")\n\n        # Read a region at a specific level (e.g., 512x512 pixels at level 2)\n        # region: Image.Image = slide.read_region((0, 0), 2, (512, 512))\n        # region.save('region_level2.png')\n\nexcept openslide.OpenSlideError as e:\n    print(f\"Error opening slide: {e}\")\nexcept FileNotFoundError:\n    print(f\"Error: Slide file not found at '{slide_path}'\")\n","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade Python environment to 3.10 or later.","message":"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.","severity":"breaking","affected_versions":">=1.3.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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).","message":"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`.","severity":"gotcha","affected_versions":"All versions on Windows"},{"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`.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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`.","cause":"The underlying OpenSlide C library or its dependencies are not found in the system's PATH or DLL search paths on Windows.","error":"ImportError: DLL load failed while importing _lowlevel: The specified module could not be found."},{"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).","cause":"The OpenSlide C library (`.dylib` on macOS, `.so` on Linux) cannot be found in standard library search paths.","error":"ImportError: Couldn't locate OpenSlide dylib"},{"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.","cause":"The file provided to `openslide.OpenSlide()` is either not a supported whole-slide image format or is corrupted.","error":"openslide.OpenSlideUnsupportedFormatError: Unsupported or corrupt file"}]}