Image.putpixel incorrectly labels supported arguments in type annotations

What did you do?

I have a JSON containing image data. It is row-major order, each pixel being an RGB triplet. Crucially, as it is JSON, it only supports lists. I wanted to use Image.putpixel in a double loop, extracting the image data out of the JSON and drawing it to an image.

What did you expect to happen?

VSCode/Pylance told me I could put a list into Image.putpixel for the value:

As JSON only supports lists, that's pretty convenient, I thought! So I implemented it exactly like that, slurping the RGB triplet out of the JSON and directly into Image.putpixel. As VSCode said, it should've worked.

What actually happened?

Traceback (most recent call last):
  File "[...]\json_to_png.py", line 12, in <module>
    img.putpixel((x, y), v)
    ~~~~~~~~~~~~^^^^^^^^^^^
  File "C:\Users\[...]\AppData\Roaming\Python\Python313\site-packages\PIL\Image.py", line 2096, in putpixel
    return self.im.putpixel(xy, value)
           ~~~~~~~~~~~~~~~~^^^^^^^^^^^
TypeError: color must be int or tuple

As the error implies, changing v to tuple(v) fixes the program, and the expected image output works fine.

What are your OS, Python and Pillow versions?

• OS: Windows 10 22H2
• Python: 3.13.2
• Pillow: 12.2.0

--------------------------------------------------------------------
Pillow 12.2.0
Python 3.13.2 (tags/v3.13.2:4f8bb39, Feb  4 2025, 15:23:48) [MSC v.1942 64 bit (AMD64)]
--------------------------------------------------------------------
Python executable is C:\Program Files\Python313\python.exe
System Python files loaded from C:\Program Files\Python313
--------------------------------------------------------------------
Python Pillow modules loaded from C:\Users\[...]\AppData\Roaming\Python\Python313\site-packages\PIL
Binary Pillow modules loaded from C:\Users\[...]\AppData\Roaming\Python\Python313\site-packages\PIL
--------------------------------------------------------------------
--- PIL CORE support ok, compiled for 12.2.0
--- TKINTER support ok, loaded 8.6
--- FREETYPE2 support ok, loaded 2.14.3
--- LITTLECMS2 support ok, loaded 2.18
--- WEBP support ok, loaded 1.6.0
--- AVIF support ok, loaded 1.4.1
--- JPEG support ok, compiled for libjpeg-turbo 3.1.4.1
--- OPENJPEG (JPEG2000) support ok, loaded 2.5.4
--- ZLIB (PNG/ZIP) support ok, loaded 1.3.1.zlib-ng, compiled for zlib-ng 2.3.3
--- LIBTIFF support ok, loaded 4.7.1
*** RAQM (Bidirectional Text) support not installed
*** LIBIMAGEQUANT (Quantization method) support not installed
*** XCB (X protocol) support not installed
--------------------------------------------------------------------

Reproducible Example

from PIL import Image

img = Image.new("RGB", (1,1))
img.putpixel((0, 0), [255, 255, 255])

Technical Info

In src/PIL/Image.py on line 2177, value is declared as following:

value: float | tuple[int, ...] | list[int]

From the fact this errors (as shown above), and based on the error itself, this appears to be the correct annotation:

value: int | tuple[int, ...]

This issue doesn't seem to affect Image.getpixel, as that actually does support lists from my testing.
This issue has arisen in 238110303c7bf829c0e56e5f721bcd80ad715699.
The argument xy also has an opposite issue where it supports list arguments but the annotation says it doesn't. This doesn't really affect development though so it's not a huge deal.

Start in src/PIL/Image.py around line 2177 and compare the putpixel annotation with the runtime behavior shown in the reproducible example. Check the related getpixel and xy annotations for consistency, then run the existing test suite or relevant image tests; done means supported putpixel arguments are accurately represented for type checkers.