From 865b7133ae2f05262afa0808d858a675effb029f Mon Sep 17 00:00:00 2001
From: Andrew Murray <radarhere@users.noreply.github.com>
Date: Thu, 23 Apr 2026 21:44:03 +1000
Subject: [PATCH] Deprecate putpixel value lists

---
 Tests/test_image_access.py   |  5 +++++
 docs/deprecations.rst        | 11 +++++++++--
 docs/releasenotes/13.0.0.rst |  6 ++++++
 src/PIL/Image.py             |  5 ++++-
 4 files changed, 24 insertions(+), 3 deletions(-)

diff --git a/Tests/test_image_access.py b/Tests/test_image_access.py
index ee8a92d5eaf..c82c9e1d157 100644
--- a/Tests/test_image_access.py
+++ b/Tests/test_image_access.py
@@ -119,6 +119,11 @@ def test_numpy(self) -> None:
         assert numpy is not None
         assert px[numpy.int32(1), numpy.int32(2)] == (18, 20, 59)
 
+    def test_deprecation(self) -> None:
+        im = Image.new("PA", (1, 1))
+        with pytest.warns(DeprecationWarning, match="'value' lists"):
+            im.putpixel((0, 0), [0, 0, 0])  # type: ignore[arg-type]
+
 
 class TestImageGetPixel:
     @staticmethod
diff --git a/docs/deprecations.rst b/docs/deprecations.rst
index 6ee46a0a76a..e414fe9a2c8 100644
--- a/docs/deprecations.rst
+++ b/docs/deprecations.rst
@@ -21,7 +21,7 @@ ExifTags.IFD.Makernote
 ``ExifTags.IFD.MakerNote``.
 
 Image getdata()
-~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^
 
 .. deprecated:: 12.1.0
 
@@ -30,9 +30,16 @@ Image getdata()
 identical, except that it returns a tuple of pixel values, instead of an internal
 Pillow data type.
 
+Image.putpixel 'value' lists
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. deprecated:: 13.0.0
+
+Passing lists to the ``value`` parameter of :py:meth:`~PIL.Image.Image.putpixel` have
+been deprecated. Use tuples instead.
 
 JpegImageFile.load_djpeg
-~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^^
 
 .. deprecated:: 13.0.0
 
diff --git a/docs/releasenotes/13.0.0.rst b/docs/releasenotes/13.0.0.rst
index b2bce2a84a4..68a31360e40 100644
--- a/docs/releasenotes/13.0.0.rst
+++ b/docs/releasenotes/13.0.0.rst
@@ -69,6 +69,12 @@ ImageCms.ImageCmsProfile.product_name and .product_info
 Deprecations
 ============
 
+Image.putpixel 'value' lists
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Passing lists to the ``value`` parameter of :py:meth:`~PIL.Image.Image.putpixel` have
+been deprecated. Use tuples instead.
+
 JpegImageFile.load_djpeg
 ^^^^^^^^^^^^^^^^^^^^^^^^
 
diff --git a/src/PIL/Image.py b/src/PIL/Image.py
index c50cb777981..d0f20f2a2c3 100644
--- a/src/PIL/Image.py
+++ b/src/PIL/Image.py
@@ -2180,7 +2180,7 @@ def putpalette(
     def putpixel(
         self,
         xy: tuple[int, int] | list[int],
-        value: float | tuple[int, ...] | list[int],
+        value: float | tuple[int, ...],
     ) -> None:
         """
         Modifies the pixel at the given position. The color is given as
@@ -2210,6 +2210,9 @@ def putpixel(
             and isinstance(value, (list, tuple))
             and len(value) in [3, 4]
         ):
+            if isinstance(value, list):  # type: ignore[unreachable]
+                deprecate("'value' lists", 14, "tuples", plural=True)  # type: ignore[unreachable]
+
             # RGB or RGBA value for a P or PA image
             if self.mode == "PA":
                 alpha = value[3] if len(value) == 4 else 255