WARNING: pip is being invoked by an old script wrapper. This will fail in a future version of pip.

What This Error Means

You're running pip through an outdated entrypoint script. It still works today, but it can break after pip upgrades.

How to Fix It

1. Preferred: switch to python -m pip ... everywhere (scripts, CI, docs).
2. If you need the wrapper, reinstall pip in the active environment so wrappers are regenerated (python -m pip install --force-reinstall pip).
3. Remove PATH entries for old Python installs or ensure the intended environment comes first.

Why It Happens

• You upgraded pip but your PATH still points to an older pip wrapper script.
• Multiple Python environments exist and PATH is selecting the wrong one.
• You are mixing system/user installs (or using sudo sometimes and not others).

How to Verify

1. Run python -m pip --version and confirm it points to the expected environment.
2. Re-run your pip command and confirm the wrapper warning no longer appears.

Manual wrapper checks

1. Check which pip wrapper you're calling: command -v pip (or where pip on Windows).
2. Compare with the interpreter: python -c 'import sys; print(sys.executable)' and python -m pip --version.
3. If in a venv, confirm it's activated.

Common CLI Output

WARNING: pip is being invoked by an old script wrapper. This will fail in a future version of pip.

Why pip wrapper scripts get stale

1. pip is typically launched via a small wrapper script (pip, pip3, or pip.exe) created when pip is installed.
2. If your PATH points to an old wrapper while the pip package has been upgraded (or installed elsewhere), pip warns that the wrapper may become incompatible.

Prevention Tips

• Standardize on python -m pip in team docs and automation.
• Avoid sudo pip ... (it commonly creates ownership and wrapper confusion).
• Use per-project virtual environments and keep PATH minimal.

Where This Can Be Triggered

def _wrapper(args: list[str] | None = None) -> int:
    """Central wrapper for all old entrypoints.

    Historically pip has had several entrypoints defined. Because of issues
    arising from PATH, sys.path, multiple Pythons, their interactions, and most
    of them having a pip installed, users suffer every time an entrypoint gets
    moved.

    To alleviate this pain, and provide a mechanism for warning users and
    directing them to an appropriate place for help, we now define all of
    our old entrypoints as wrappers for the current one.
    """
    sys.stderr.write(
        "WARNING: pip is being invoked by an old script wrapper. This will "
        "fail in a future version of pip.\n"
        "Please see https://github.com/pypa/pip/issues/5599 for advice on "
        "fixing the underlying issue.\n"
        "To avoid this problem you can invoke Python with '-m pip' instead of "
        "running pip directly.\n"
    )
    return main(args)