We could probably just point to PIL.Image.open here. If I understand the PIL docs this list of formats depends on your installed libraries, so I'm not sure we can or should explicitly list the allowed formats. Also, these things are pretty standard.

We special case png to a known fast path (which is probably an artifact of us formerly owning a wrapping of lib png) and some special casing of urls, but otherwise we fall back to PIL.Image.open. That is probably worth noting (and directing people to please do that directly and not use imread!).

I have several concerns about documenting supported extension here. As @jklymak points out the list may depend on exactly how PIL is compiled or what other libraries are installed, we do not want to document any normalization / aliasing that PIL may do (as if they change that then our docs would be wrong!), and finally the extension on a filename is at best a hint of what is actually in the file (I can name a png blah_blah.jpeg). Almost all file formats have some "magic bytes" at the start to identify them (see https://en.wikipedia.org/wiki/List_of_file_signatures), I expect that PIL has some fallback paths where it reads the first couple of bytes and then dispatches based on that.

TLDR: 👍 on linking to PIL.Image.open 👎 on listing anything about file extensions.

please do that directly and not use imread

Are you saying you think imread should be removed from matplotlib? That actually would make more sense to me, if it's essentially just a wrapper for PIL.Image.open

Yes it is a vestige of when PIL was a difficult dependency/didn't exist. Also Matplotlib has a legacy in matlab, which has imread. I think there is general consensus that we should try to stick to just plotting and not emulate everything matlab does. OTOH deprecations are painful particularly for simple wrappers, so...

Just for context of how I ended up frustrated with the docs, I ran into this problem:

And solved it like this:

from PIL import Image
import requests
import matplotlib.pyplot as plt
url = small_df.at[0, 'image_url']
response = requests.get(url, stream=True)
img = Image.open(response.raw)
plt.imshow(img)
plt.show()

I didn't know at the time that Matplotlib was using PIL behind the scenes, but that was my solution anyways.

Are you saying you think imread should be removed from matplotlib?

If we were starting from scratch I would be against putting it in, but it has been there from 2004 and removing it would break a lot of people for mostly aesthetic reasons...so it stays.