{"id":8377,"library":"openslide-bin","title":"OpenSlide Binary Distribution for Python","description":"openslide-bin is a pip-installable, self-contained build of the OpenSlide C library and its essential dependencies for Windows, macOS, and Linux. It is maintained by the OpenSlide project to simplify the installation of the native OpenSlide library, which is required by the `openslide-python` bindings for reading whole-slide images (WSI). The current version is 4.0.0.13, and releases are tied to OpenSlide C library updates and build fixes.","status":"active","version":"4.0.0.13","language":"en","source_language":"en","source_url":"https://github.com/openslide/openslide-bin","tags":["image processing","digital pathology","whole-slide imaging","WSI","medical imaging","bindings"],"install":[{"cmd":"pip install openslide-bin openslide-python","lang":"bash","label":"Recommended Installation"},{"cmd":"pip install openslide-bin","lang":"bash","label":"Install OpenSlide binaries only"}],"dependencies":[{"reason":"openslide-bin provides the native C library that openslide-python (the Python bindings) depends on to function. Users typically install both.","package":"openslide-python","optional":false},{"reason":"Required by openslide-python for image manipulation and region extraction.","package":"Pillow","optional":false}],"imports":[{"note":"The `openslide-bin` package provides the native library, not Python modules directly. Python bindings are in `openslide-python` which is imported as `openslide`.","wrong":"import openslide-bin","symbol":"OpenSlide","correct":"import openslide"}],"quickstart":{"code":"import os\nimport openslide\nfrom PIL import Image\n\n# NOTE: For Windows, if you encounter 'DLL load failed' or 'cannot find OpenSlide library',\n# you might need to manually specify the path to the openslide-bin 'bin' directory.\n# Example: openslide_bin_path = os.path.join(os.path.dirname(os.path.abspath(__file__)), 'openslide-win64-20231011', 'bin')\n# if os.name == 'nt':\n#     os.add_dll_directory(openslide_bin_path)\n\n# Placeholder for a whole-slide image file. Replace with your .svs, .ndpi, etc.\n# You can download sample slides from openslide.org/demo\nslide_path = os.environ.get('OPENSLIDE_SAMPLE_SLIDE_PATH', 'path/to/your/slide.svs')\n\ntry:\n    with openslide.OpenSlide(slide_path) as slide:\n        print(f\"Opened slide: {slide_path}\")\n        print(f\"Dimensions (level 0): {slide.dimensions}\")\n        print(f\"Level count: {slide.level_count}\")\n        print(f\"Properties: {slide.properties.keys()}\")\n\n        # Get a thumbnail of the slide\n        thumbnail = slide.get_thumbnail((500, 500))\n        thumbnail.save('slide_thumbnail.png')\n        print(\"Saved thumbnail to slide_thumbnail.png\")\n\n        # Read a region from a specific level\n        # For example, read a 256x256 region from the highest resolution (level 0)\n        # starting at (0, 0) pixel coordinates.\n        region_image = slide.read_region((0, 0), 0, (256, 256))\n        region_image.save('slide_region_level0.png')\n        print(\"Saved a 256x256 region from level 0 to slide_region_level0.png\")\n\nexcept openslide.OpenSlideError as e:\n    print(f\"Error opening slide: {e}\")\n    print(\"Please ensure the slide path is correct and the file is a supported OpenSlide format.\")\nexcept FileNotFoundError:\n    print(f\"Error: Slide file not found at {slide_path}\")\nexcept Exception as e:\n    print(f\"An unexpected error occurred: {e}\")","lang":"python","description":"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."},"warnings":[{"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`)","message":"Python 3.8 support was dropped in openslide-bin v4.0.0.10. Ensure your Python environment is 3.9 or newer.","severity":"breaking","affected_versions":">=4.0.0.10"},{"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`.","message":"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.","severity":"gotcha","affected_versions":"All"},{"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`.","message":"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`.","severity":"gotcha","affected_versions":"All on Windows"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Install the Python bindings: `pip install openslide-python`. Remember that `openslide-bin` provides the C library, not the Python module itself.","cause":"The `openslide-python` package, which provides the `openslide` module, is not installed or not accessible in the current Python environment.","error":"ModuleNotFoundError: No module named 'openslide'"},{"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`.","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.","error":"OSError: cannot find OpenSlide library\nOR\nWindowsError: [Error 126] The specified module could not be found\nOR\nOSError: dlopen(libopenslide.0.dylib, 6): image not found"},{"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.","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.","error":"openslide.OpenSlideUnsupportedFormatError: file not a OpenSlide compatible whole slide image"}]}