pandas-dev/pandas · error · OptionError

Option '{key}' has already been defined as deprecated.

Error message

Option '{key}' has already been defined as deprecated.

What it means

Raised by deprecate_option (config.py:649-650) when the lowercased key is already present in _deprecated_options. Each option can be deprecated at most once; the deprecation metadata is immutable once set.

Source

Thrown at pandas/_config/config.py:650

    rkey : str, optional
        Name of an option to reroute access to.
        If specified, any referenced `key` will be
        re-routed to `rkey` including set/get/reset.
        rkey must be a fully-qualified option name (e.g "x.y.z.rkey").
        used by the default message if no `msg` is specified.
    removal_ver : str, optional
        Specifies the version in which this option will
        be removed. used by the default message if no `msg` is specified.

    Raises
    ------
    OptionError
        If the specified key has already been deprecated.
    """
    key = key.lower()

    if key in _deprecated_options:
        raise OptionError(f"Option '{key}' has already been defined as deprecated.")

    _deprecated_options[key] = DeprecatedOption(key, category, msg, rkey, removal_ver)


#
# functions internal to the module


def _select_options(pat: str) -> list[str]:
    """
    returns a list of keys matching `pat`

    if pat=="all", returns all registered options
    """
    # short-circuit for exact key
    if pat in _registered_options:
        return [pat]

View on GitHub (pinned to 71959b8cb9)

Solutions

1. Guard with `if key not in cf._deprecated_options:` before deprecating.
2. Idempotently skip if already deprecated by checking the dict first.
3. Use unique per-library keys so two libraries do not collide on deprecation.

Example fix

# before
cf.deprecate_option('display.foo', FutureWarning)
cf.deprecate_option('display.foo', FutureWarning)  # already defined as deprecated

# after
if 'display.foo' not in cf._deprecated_options:
    cf.deprecate_option('display.foo', FutureWarning)

import pandas._config.config as cf
def safe_deprecate(key, category, **kw):
    if key.lower() in cf._deprecated_options:
        return
    cf.deprecate_option(key, category, **kw)

def is_deprecated(key: str) -> bool:
    import pandas._config.config as cf
    return key.lower() in cf._deprecated_options

from pandas.errors import OptionError
try:
    cf.deprecate_option(key, category)
except OptionError:
    pass  # already deprecated

When it happens

Trigger: cf.deprecate_option('display.foo', FutureWarning) twice, or a library that re-imports and re-deprecates the same key.

Common situations: Re-running a deprecation registration (notebook reload, double import), or two libraries deprecating the same key.

Related errors

• Option '{key}' has already been registered
• No such keys(s): {pat!r}
• Pattern matched multiple keys
• Must provide an even number of non-keyword arguments
• No such keys(s) for {pat=}

AI-assisted analysis of pandas-dev/pandas@71959b8cb9 (2026-08-07). Data as JSON: /api/errors/44a373da3219eb3c. Report an issue: GitHub.