Why PIL/Pillow getcolors() Returns None and How to Choose the Right maxcolors for Large, Detailed Images

Learn why PIL/Pillow getcolors() returns None on large images, how the maxcolors threshold works, and how to fix it by raising the limit for palette analysis.

When working with PIL and analyzing image palettes, a common surprise is seeing getcolors() return None. This usually surfaces on large or highly detailed images and can look like a bug. It isn’t—there’s a hard stop built into the API that you’re hitting.

Reproducing the issue

The behavior shows up with code as simple as this:

from PIL import Image

img_src = "path_or_url_to_image"
base_pic = Image.open(img_src)
unique_palette = base_pic.getcolors(maxcolors=100000)

On smaller images everything appears fine. On a very large image, unique_palette can be None, which is confusing at first glance.

What’s actually happening

The return value of getcolors() is tied directly to a threshold you pass in via maxcolors. If the image contains more distinct colors than this limit, getcolors() returns None. In one real-world case, the image had 250,203 colors, so a maxcolors value of 100,000 wasn’t sufficient and the call produced None.

Two simple bounds help to reason about this. The maximum possible number of unique colors cannot exceed the number of pixels in the image, which is width multiplied by height. There’s also a ceiling determined by the bit depth. For a typical 24 bit-per-pixel image, that cap is 2**24, or 16,777,216 possible colors. If an image contains more pixels than that, some colors are guaranteed to repeat.

Fixing it

The API behavior is by design. If you need the colors and know the image may exceed your current limit, raise maxcolors high enough so the call doesn’t short-circuit:

from PIL import Image

img_src = "path_or_url_to_image"
base_pic = Image.open(img_src)
color_set = base_pic.getcolors(maxcolors=100000000)

With a larger threshold, getcolors() returns the list of color-frequency pairs instead of None, even for very detailed or massive images.

Why this matters

Color analysis pipelines—palette extraction, dominant color detection, quantization pre-checks—often rely on getcolors(). If you quietly hit the threshold and end up with None, downstream logic breaks in non-obvious ways. Understanding the relationship between actual unique colors and the maxcolors limit helps you choose an appropriate threshold and avoid brittle behavior on large assets.

Practical takeaways

If you see None from getcolors(), it means the image has more distinct colors than the maxcolors value you provided. Large images can easily exceed modest thresholds; one example showed 250,203 distinct colors. The absolute number of unique colors is bounded by pixel count and by bit depth, with a common 24 bpp upper bound of 16,777,216. When in doubt, set a higher maxcolors value so your analysis doesn’t prematurely stop.