matplotlib/matplotlib · error · ValueError

The `colorizer` keyword cannot be used simultaneously with a

Error message

The `colorizer` keyword cannot be used simultaneously with any of the following keywords: {keys}

What it means

The colorizer= keyword bundles a ready-made Colorizer (cmap + norm as a unit). It is intentionally exclusive: supplying it together with cmap=, norm= (or similar configuration keywords) makes the configuration ambiguous, so _check_exclusionary_keywords raises this ValueError listing the conflicting keys.

Source

Thrown at lib/matplotlib/colorizer.py:653

            mask = np.any(mask.view('bool').reshape((*A.shape, -1)), axis=-1)
        return mask

    def changed(self):
        """
        Call this whenever the mappable is changed to notify all the
        callbackSM listeners to the 'changed' signal.
        """
        self.callbacks.process('changed', self)
        self.stale = True

    @staticmethod
    def _check_exclusionary_keywords(colorizer, **kwargs):
        """
        Raises a ValueError if any kwarg is not None while colorizer is not None
        """
        if colorizer is not None:
            if any([val is not None for val in kwargs.values()]):
                raise ValueError("The `colorizer` keyword cannot be used simultaneously"
                                 " with any of the following keywords: "
                                 + ", ".join(f'`{key}`' for key in kwargs.keys()))

    @staticmethod
    def _get_colorizer(cmap, norm, colorizer):
        if isinstance(colorizer, Colorizer):
            _ScalarMappable._check_exclusionary_keywords(
                Colorizer, cmap=cmap, norm=norm
            )
            return colorizer
        return Colorizer(cmap, norm)

# The docstrings here must be generic enough to apply to all relevant methods.
mpl._docstring.interpd.register(
    cmap_doc="""\
cmap : str or `~matplotlib.colors.Colormap`, default: :rc:`image.cmap`
    The Colormap instance or registered colormap name used to map scalar data
    to colors.""",

View on GitHub (pinned to b379c1b69e)

Solutions

1. Pass colorizer alone and move all styling into the Colorizer at construction
2. Or drop colorizer and configure with cmap=/norm= individually
3. In merged-kwargs wrappers, pop cmap/norm when colorizer is present before calling

Example fix

// before
ax.imshow(data, colorizer=cz, norm=nrm)
// after
ax.imshow(data, colorizer=cz)  // norm already inside cz
// or
ax.imshow(data, norm=nrm)  // let matplotlib build the colorizer

if colorizer is not None:
    cmap = norm = None  # or: kwargs.pop('cmap', None); kwargs.pop('norm', None)

When it happens

Trigger: ax.imshow(data, colorizer=cz, norm=nrm); plt.pcolormesh(..., colorizer=cz, cmap='viridis'); any ScalarMappable-creating API receiving colorizer alongside cmap/norm/vmin-like config kwargs.

Common situations: Gradually migrating code to the colorizer API while old kwargs remain in a shared defaults dict; wrapper functions that merge user kwargs with preset kwargs and forward everything.

Related errors

• {key} must not be an empty sequence
• 'transform' is not allowed as a keyword argument; axhline ge
• 'transform' is not allowed as a keyword argument; axvline ge
• Passing {key!r} to bar_label() is not supported.
• Supply a 'c' argument or a 'color' kwarg but not both; they

AI-assisted analysis of matplotlib/matplotlib@b379c1b69e (2026-08-21). Data as JSON: /api/errors/8e28edcaf8f69c1d. Report an issue: GitHub.