diff --git a/docs/reference/ImageGrab.rst b/docs/reference/ImageGrab.rst
index ff4646a5f..943fdf69b 100644
--- a/docs/reference/ImageGrab.rst
+++ b/docs/reference/ImageGrab.rst
@@ -9,7 +9,7 @@ or the clipboard to a PIL image memory.
.. versionadded:: 1.1.3
-.. py:function:: PIL.ImageGrab.grab(bbox=None, include_layered_windows=False, all_screens=False, xdisplay=None)
+.. py:function:: grab(bbox=None, include_layered_windows=False, all_screens=False, xdisplay=None)
Take a snapshot of the screen. The pixels inside the bounding box are
returned as an "RGBA" on macOS, or an "RGB" image otherwise.
@@ -26,12 +26,15 @@ or the clipboard to a PIL image memory.
.. versionadded:: 6.2.0
- :param xdisplay: X11 Display address. Pass ``None`` to grab the default system screen. Pass ``""`` to grab the default X11 screen on Windows or macOS.
+ :param xdisplay:
+ X11 Display address. Pass ``None`` to grab the default system screen. Pass ``""`` to grab the default X11 screen on Windows or macOS.
+
+ You can check X11 support using :py:func:`PIL.features.check_feature` with ``feature="xcb"``.
.. versionadded:: 7.1.0
:return: An image
-.. py:function:: PIL.ImageGrab.grabclipboard()
+.. py:function:: grabclipboard()
Take a snapshot of the clipboard image, if any. Only macOS and Windows are currently supported.
diff --git a/docs/reference/features.rst b/docs/reference/features.rst
new file mode 100644
index 000000000..196f938ed
--- /dev/null
+++ b/docs/reference/features.rst
@@ -0,0 +1,60 @@
+.. py:module:: PIL.features
+.. py:currentmodule:: PIL.features
+
+:py:mod:`features` Module
+==========================
+
+The :py:mod:`PIL.features` module can be used to detect which Pillow features are available on your system.
+
+.. autofunction:: PIL.features.pilinfo
+.. autofunction:: PIL.features.check
+.. autofunction:: PIL.features.get_supported
+
+Modules
+-------
+
+Support for the following modules can be checked:
+
+* ``pil``: The Pillow core module, required for all functionality.
+* ``tkinter``: Tkinter support.
+* ``freetype2``: FreeType font support via :py:func:`PIL.ImageFont.truetype`.
+* ``littlecms2``: LittleCMS 2 support via :py:mod:`PIL.ImageCms`.
+* ``webp``: WebP image support.
+
+.. autofunction:: PIL.features.check_module
+.. autofunction:: PIL.features.get_supported_modules
+
+Codecs
+------
+
+These are only checked during Pillow compilation.
+If the required library was uninstalled from the system, the ``pil`` core module may fail to load instead.
+
+Support for the following codecs can be checked:
+
+* ``jpg``: (compile time) Libjpeg support, required for JPEG based image formats.
+* ``jpg_2000``: (compile time) OpenJPEG support, required for JPEG 2000 image formats.
+* ``zlib``: (compile time) Zlib support, required for zlib compressed formats, such as PNG.
+* ``libtiff``: (compile time) LibTIFF support, required for TIFF based image formats.
+
+.. autofunction:: PIL.features.check_codec
+.. autofunction:: PIL.features.get_supported_codecs
+
+Features
+--------
+
+Some of these are only checked during Pillow compilation.
+If the required library was uninstalled from the system, the relevant module may fail to load instead.
+
+Support for the following features can be checked:
+
+* ``libjpeg_turbo``: (compile time) Whether Pillow was compiled against the libjpeg-turbo version of libjpeg.
+* ``transp_webp``: Support for transparency in WebP images.
+* ``webp_mux``: (compile time) Support for EXIF data in WebP images.
+* ``webp_anim``: (compile time) Support for animated WebP images.
+* ``raqm``: Raqm library, required for ``ImageFont.LAYOUT_RAQM`` in :py:func:`PIL.ImageFont.truetype`.
+* ``libimagequant``: (compile time) ImageQuant quantization support in :py:func:`PIL.Image.Image.quantize`.
+* ``xcb``: (compile time) Support for X11 in :py:func:`PIL.ImageGrab.grab` via the XCB library.
+
+.. autofunction:: PIL.features.check_feature
+.. autofunction:: PIL.features.get_supported_features
diff --git a/docs/reference/index.rst b/docs/reference/index.rst
index 8c09e7b67..91cde0400 100644
--- a/docs/reference/index.rst
+++ b/docs/reference/index.rst
@@ -30,6 +30,7 @@ Reference
PSDraw
PixelAccess
PyAccess
+ features
../PIL
plugins
internal_design
diff --git a/src/PIL/Image.py b/src/PIL/Image.py
index 930252023..9d94bce0e 100644
--- a/src/PIL/Image.py
+++ b/src/PIL/Image.py
@@ -1051,10 +1051,12 @@ class Image:
of colors.
:param colors: The desired number of colors, <= 256
- :param method: 0 = median cut
- 1 = maximum coverage
- 2 = fast octree
- 3 = libimagequant
+ :param method: ``Image.MEDIANCUT=0`` (median cut),
+ ``Image.MAXCOVERAGE=1`` (maximum coverage),
+ ``Image.FASTOCTREE=2`` (fast octree),
+ ``Image.LIBIMAGEQUANT=3`` (libimagequant; check support using
+ :py:func:`PIL.features.check_feature`
+ with ``feature="libimagequant"``).
:param kmeans: Integer
:param palette: Quantize to the palette of given
:py:class:`PIL.Image.Image`.
diff --git a/src/PIL/ImageFont.py b/src/PIL/ImageFont.py
index 25ceaa16a..79c161713 100644
--- a/src/PIL/ImageFont.py
+++ b/src/PIL/ImageFont.py
@@ -637,6 +637,11 @@ def truetype(font=None, size=10, index=0, encoding="", layout_engine=None):
encoding of any text provided in subsequent operations.
:param layout_engine: Which layout engine to use, if available:
`ImageFont.LAYOUT_BASIC` or `ImageFont.LAYOUT_RAQM`.
+
+ You can check support for Raqm layout using
+ :py:func:`PIL.features.check_feature` with ``feature="raqm"``.
+
+ .. versionadded:: 4.2.0
:return: A font object.
:exception OSError: If the file could not be read.
"""
diff --git a/src/PIL/features.py b/src/PIL/features.py
index ac06c0f71..33e89cf24 100644
--- a/src/PIL/features.py
+++ b/src/PIL/features.py
@@ -17,6 +17,13 @@ modules = {
def check_module(feature):
+ """
+ Checks if a module is available.
+
+ :param feature: The module to check for.
+ :returns: ``True`` if available, ``False`` otherwise.
+ :raises ValueError: If the module is not defined in this version of Pillow.
+ """
if not (feature in modules):
raise ValueError("Unknown module %s" % feature)
@@ -30,6 +37,9 @@ def check_module(feature):
def get_supported_modules():
+ """
+ :returns: A list of all supported modules.
+ """
return [f for f in modules if check_module(f)]
@@ -37,6 +47,13 @@ codecs = {"jpg": "jpeg", "jpg_2000": "jpeg2k", "zlib": "zip", "libtiff": "libtif
def check_codec(feature):
+ """
+ Checks if a codec is available.
+
+ :param feature: The codec to check for.
+ :returns: ``True`` if available, ``False`` otherwise.
+ :raises ValueError: If the codec is not defined in this version of Pillow.
+ """
if feature not in codecs:
raise ValueError("Unknown codec %s" % feature)
@@ -46,6 +63,9 @@ def check_codec(feature):
def get_supported_codecs():
+ """
+ :returns: A list of all supported codecs.
+ """
return [f for f in codecs if check_codec(f)]
@@ -61,6 +81,13 @@ features = {
def check_feature(feature):
+ """
+ Checks if a feature is available.
+
+ :param feature: The feature to check for.
+ :returns: ``True`` if available, ``False`` if unavailable, ``None`` if unknown.
+ :raises ValueError: If the feature is not defined in this version of Pillow.
+ """
if feature not in features:
raise ValueError("Unknown feature %s" % feature)
@@ -74,10 +101,20 @@ def check_feature(feature):
def get_supported_features():
+ """
+ :returns: A list of all supported features.
+ """
return [f for f in features if check_feature(f)]
def check(feature):
+ """
+ :param feature: A module, feature, or codec name.
+ :returns:
+ ``True`` if the module, feature, or codec is available,
+ ``False`` or ``None`` otherwise.
+ """
+
if feature in modules:
return check_module(feature)
if feature in codecs:
@@ -89,6 +126,10 @@ def check(feature):
def get_supported():
+ """
+ :returns: A list of all supported modules, features, and codecs.
+ """
+
ret = get_supported_modules()
ret.extend(get_supported_features())
ret.extend(get_supported_codecs())
@@ -96,6 +137,16 @@ def get_supported():
def pilinfo(out=None, supported_formats=True):
+ """
+ Prints information about this installation of Pillow.
+ This function can be called with ``python -m PIL``.
+
+ :param out:
+ The output stream to print to. Defaults to ``sys.stdout`` if ``None``.
+ :param supported_formats:
+ If ``True``, a list of all supported image file formats will be printed.
+ """
+
if out is None:
out = sys.stdout