{"id":2830,"library":"types-pillow","title":"Typing stubs for Pillow","description":"types-Pillow is a PEP 561 type stub package that provides external type annotations for the Pillow library. It enables static type checkers like mypy, pyright, and PyCharm to perform type checking on code that uses Pillow. This package specifically targets Pillow versions up to 10.2.x. Pillow versions 10.3.0 and newer now include their type annotations directly within the library, making this stub package unnecessary for those versions.","status":"maintenance","version":"10.2.0.20240822","language":"en","source_language":"en","source_url":"https://github.com/python/typeshed","tags":["typing","stubs","type hints","pillow","pil","image processing"],"install":[{"cmd":"pip install types-pillow","lang":"bash","label":"Install types-pillow"}],"dependencies":[{"reason":"This package provides type stubs for the Pillow library. While not a runtime dependency of 'types-pillow' itself, it is required for your application to actually use the types provided. Ensure version compatibility, e.g., types-Pillow==10.2.* targets Pillow==10.2.*.","package":"Pillow","optional":false}],"imports":[{"note":"You import from the runtime library (Pillow, via `PIL`), not directly from the stub package (`types-pillow`). The type checker automatically uses the stubs from `types-pillow` when `PIL` is imported.","wrong":"from types_pillow import Image","symbol":"Image","correct":"from PIL import Image"}],"quickstart":{"code":"from PIL import Image\nfrom typing import TYPE_CHECKING\nimport os\n\n# The 'types-pillow' package provides type hints for Pillow\n# You don't directly import from types_pillow for usage; it's picked up by type checkers.\n\ndef process_image(img_path: str) -> Image.Image:\n    \"\"\"Opens an image, converts it to grayscale, and returns it.\"\"\"\n    try:\n        with Image.open(img_path) as img:\n            # Type checkers will use the stubs provided by types-pillow\n            grayscale_img: Image.Image = img.convert(\"L\")\n            return grayscale_img\n    except FileNotFoundError:\n        print(f\"Error: Image at {img_path} not found.\")\n        # In a real application, you might raise an error or return a default image.\n        # For demonstration, we'll return a new blank image.\n        return Image.new(\"L\", (1, 1))\n\nif __name__ == \"__main__\":\n    # Create a dummy image for the example if it doesn't exist\n    dummy_image_path = \"test_image.jpg\"\n    try:\n        Image.new(\"RGB\", (100, 100), color='red').save(dummy_image_path)\n    except Exception:\n        pass # Ignore if it fails, e.g., in a read-only environment\n\n    processed = process_image(dummy_image_path)\n    print(f\"Processed image mode: {processed.mode}, size: {processed.size}\")\n    # processed.show() # Uncomment to display the image (might open an external viewer)\n\n    # Clean up dummy image\n    if os.path.exists(dummy_image_path):\n        os.remove(dummy_image_path)\n","lang":"python","description":"This example demonstrates how to use Pillow with type hints. When `types-pillow` is installed, a static type checker (like MyPy) will understand the types of `PIL.Image.Image` and its methods, helping to catch errors at development time. You interact with the `PIL` library directly, and `types-pillow` works in the background."},"warnings":[{"fix":"If `Pillow >= 10.3.0` is installed: `pip uninstall types-pillow`","message":"Pillow versions 10.3.0 and newer include their type annotations directly within the Pillow package itself (via `py.typed`). If you are using Pillow 10.3.0 or a later version, you MUST uninstall `types-Pillow` to avoid duplicate type definitions and potential type-checking conflicts.","severity":"breaking","affected_versions":"Pillow >= 10.3.0, types-Pillow (all versions when used with Pillow >= 10.3.0)"},{"fix":"Align your `types-Pillow` version with your `Pillow` version in your `requirements.txt` or `pyproject.toml` (e.g., `Pillow==10.2.0` and `types-Pillow==10.2.0.YYYYMMDD`).","message":"The version of `types-Pillow` should ideally match the major.minor version of your installed `Pillow` library to ensure accurate type checking. For example, `types-Pillow==10.2.*` provides stubs for `Pillow==10.2.*`. Mismatched versions can lead to incorrect type hints or type-checking errors.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Update your code to use the `PIL.Image.Resampling` enum for image filters, e.g., `img.resize(size, PIL.Image.Resampling.LANCZOS)` instead of `img.resize(size, PIL.Image.LANCZOS)`.","message":"In `Pillow > 9.1.0`, image filter constants (like `PIL.Image.LANCZOS`) were deprecated in favor of the `PIL.Image.Resampling` enum (e.g., `PIL.Image.Resampling.LANCZOS`). If you're using a newer `Pillow` (and `types-Pillow` that reflects this change) but your code still uses the old constants, type checkers will report errors.","severity":"gotcha","affected_versions":"Pillow > 9.1.0, types-Pillow > 9.1.x.YYYYMMDD"}],"env_vars":null,"last_verified":"2026-04-10T00:00:00.000Z","next_check":"2026-07-09T00:00:00.000Z"}