pypa/pip · error · PipDeprecationWarning

DEPRECATION: {reason} pip {gone_in} will enforce this behavi

Error message

DEPRECATION: {reason} pip {gone_in} will enforce this behaviour change.

What it means

Raised as PipDeprecationWarning (promoted to an error when is_gone is True, i.e. pip's current version >= gone_in version) when deprecated functionality has reached its scheduled removal version. Before the removal version it is emitted as a warning via warnings.warn; at or past gone_in, the deprecated() function raises it as an exception, halting the operation. The message includes the reason, the enforcing version, and optionally a replacement suggestion and feature flag.

Source

Thrown at src/pip/_internal/utils/deprecation.py:140

                if not is_gone
                else None
            ),
        ),
        (
            issue,
            "Discussion can be found at https://github.com/pypa/pip/issues/{}",
        ),
    ]

    message = " ".join(
        format_str.format(value)
        for value, format_str in message_parts
        if format_str is not None and value is not None
    )

    # Raise as an error if this behaviour is deprecated.
    if is_gone:
        raise PipDeprecationWarning(message)

    warning = PipDeprecationWarning(message)
    warning.include_source = include_source
    warnings.warn(warning, stacklevel=stacklevel)

View on GitHub (pinned to f399c37189)

Solutions

1. Read the deprecation message for the suggested replacement and migrate to it.
2. Remove the deprecated flag or option from your pip invocation or requirements.
3. Pin to an older pip version (`python -m pip install pip==<gone_in_prev>`) only as a temporary stopgap while migrating.
4. If running pip's tests, ensure you are not triggering genuinely deprecated internal APIs in your test code.

Example fix

// before
$ pip install --use-deprecated=legacy-resolver pkg

// after
$ pip install pkg  # resolver deprecation removed, use default

import subprocess, sys

def pip_supports_feature(flag: str) -> bool:
    """Check if the current pip version still supports a flag."""
    result = subprocess.run(
        [sys.executable, '-m', 'pip', '--help'],
        capture_output=True, text=True
    )
    return flag in result.stdout

# Before using a deprecated flag, verify it still exists

def is_deprecated_flag_removed(flag: str, pip_help_output: str) -> bool:
    """True if the flag is absent from pip --help (likely removed)."""
    return flag not in pip_help_output

When it happens

Trigger: Calling deprecated() with a gone_in parameter whose version is <= the running pip version. In test environments, _PIP_TEST_ENV is set which promotes all PipDeprecationWarning to errors via warnings.simplefilter('error', PipDeprecationWarning) at deprecation.py:54, so even pre-removal deprecations will raise.

Common situations: Upgrading pip to a newer version that has removed a feature you relied on. Using deprecated flags like --use-deprecated=legacy-resolver after its removal version. Running pip's own test suite (which sets _PIP_TEST_ENV and turns all deprecation warnings into errors).

Related errors

• No module named {module!r}
• Ill-formed name/version string: '%s'
• Cannot restore Version from {state!r}
• Use of .. or absolute path in a resource path is not allowed

AI-assisted analysis of pypa/pip@f399c37189 (2026-08-08). Data as JSON: /api/errors/b4c34be9385942dc. Report an issue: GitHub.