Deprecate getdata(), in favour of new get_flattened_data()

[radarhere]

#9261 reports that pyright has a problem when iterating over the core Imaging instance returned from im.getdata().

There is already a comment in our codebase that returning a core Imaging instance from getdata() is a potential pitfall.

Pillow/src/PIL/Image.py

Line 1447 in 76f04b4

return self.im # could be abused

It would be better for users not to be given a C object they are unfamiliar with.

While users could adapt their code to getchannel() and tobytes() with some manipulation instead, I expect there would be pushback against removing this method entirely.

In practice, I expect that we could just change the output to a tuple, and most if not all code would continue to work, but I understand that changing the return type suddenly is not great in theory.

So this PR suggests deprecating the method, as a replacement, I have added get_flattened_data(), converting the core Imaging instance to a tuple.

[hugovk]

Do we have an idea of how widely used getdata is?

[hugovk]

Suggested change

	.. deprecated:: 12.2.0
	.. deprecated:: 12.1.0

And update from docs/releasenotes/12.2.0.rst

[radarhere]

.getdata() has 72.4k results. We don't have a monopoly on getdata(), but considering that im.getdata() has 5k results, img.data() has 11k results and image.getdata() has 19.6k results, I don't think the number is that far off.

[hugovk]

That is quite a lot, but we can try it and see how it goes.

[akx]

Hmm. get_flattened_data() isn't a great drop-in replacement for getdata(), since the new function eagerly allocates Python objects for each pixel in the image, even when not accessed, and for, say, the 1237x811 RGB image from the benchmarks, that's roughly a million 3-tuples, and a lot of GC pressure...

I would maybe reconsider the full deprecation of getdata(), since lazy access to image pixels in a linear format sounds like a good idea to still have. Would you be open to a PR that has getdata() return a (fast) less-abusable limited access object instead? (I'll also try and figure out what effbot meant with "# could be abused"...)

(EDIT: another option could be to to allow PixelAccess objects, as returned from .load(), to be indexed via integers, and then just return that...)

[radarhere]

since lazy access to image pixels in a linear format sounds like a good idea to still have

Could you expand upon this scenario? If it wasn't linear, I'd say that getpixel() is available for lazy access. If it is linear, I'd say that get_flattened_data() for non-lazy access. When do you imagine users want to both lazy access and in a linear order?

I'll also try and figure out what effbot meant with "# could be abused"...

I think it just meant that the C API is not intended to be called by user Python code, and getdata() might be encouraging them to do so.

[akx]

Could you expand upon this scenario?

get_flattened_data()'d data requires a surprising multiplier of memory compared to the raw image data. Sorry for the non-scientific measurement:

$ python3
Python 3.14.6 (main, Jun 10 2026, 10:03:53) [Clang 17.0.0 (clang-1700.6.4.2)] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>> # macOS's Activity Monitor shows this Python to use 14.1 MB of memory
>>> from PIL import Image
>>> i = Image.new("RGB", (1024, 1024), 42)
>>> # macOS's Activity Monitor shows this Python to use 21.7 MB of memory
>>> t = i.get_flattened_data()
>>> # macOS's Activity Monitor shows this Python to use 118.4 MB of memory

(and I think peak memory during get_flattened_data() is higher than that, even)

I could see that users switching to get_flattened_data() for familiar getdata() usecases end up with OOMs there with suitably large images.

Memory blow-up aside, (lazy) linear iterators interop with the standard library/idioms (that don't work with PixelAccess that requires x,y tuples, or getpixel that... isn't an iterable 😄). Some ideas off the top of my head:

• zip(im1.getdata(), im2.getdata()) to compare two images pixel by pixel and early-exit upon the first difference. With get_flattened_data(), you'd pay upfront to materialize all pixels twice.
• Counter(im.getdata()) doesn't materialize all pixel tuples into memory in advance just for Counter() to hash them and throw most instances away.

I think it just meant that the C API is not intended to be called by user Python code, and getdata() might be encouraging them to do so.

Yeap. As said, I can do the work to have getdata() return a lazy ImagingLinearAccess object instead of the full ImagingCore 👍

[radarhere]

I can do the work to have getdata() return a lazy ImagingLinearAccess object instead of the full ImagingCore

My idea would be to return a Python class, rather than C, that calls getpixel() from a magic method. However, I recognise that you are likely to prefer C for performance reasons.