pypa/pip · error · CommandError

Cannot combine '--path' with '--user' or '--local'

Error message

Cannot combine '--path' with '--user' or '--local'

What it means

Raised as CommandError by check_list_path_option (cmdoptions.py:1289) when `pip list` is given both --path and either --user or --local. The --path option restricts listing to a specific installation directory (lines 1276-1284), which is conceptually orthogonal to the --user (user site-packages) and --local (current environment only) scopes, so combining them is ambiguous and rejected at line 1288.

Solutions

1. Drop --user/--local and rely solely on --path <dir> to scope the listing to that directory.
2. Or drop --path and use --user / --local alone.

Example fix

# before
pip list --path /opt/venv/lib/site-packages --user
# after
pip list --path /opt/venv/lib/site-packages

# Enforce mutual exclusivity of pip list scope flags.
def validate_list_scope(opts):
    if opts.get("path") and (opts.get("user") or opts.get("local")):
        raise ValueError("--path cannot be combined with --user or --local")
    return True

When it happens

Trigger: `pip list --path /opt/venv/lib/python3.11/site-packages --user` or `pip list --path <dir> --local`.

Common situations: Debugging where a package is installed and stacking scope flags hoping to narrow results; converting a --user/--local workflow to inspect a custom path without removing the old flag.

Related errors

• Cannot use '--only-dependencies' in combination with
• Could not locate Python interpreter
• --pre cannot be used with --all-releases or --only-final.
• --require-hashes and --no-require-hashes are mutually…
• --build-constraint cannot be used with --no-build-isolation.

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

Appendix: source

Thrown at src/pip/_internal/cli/cmdoptions.py:1289

    help="Do not automatically enable --require-hashes "
    "when encountering a requirement with hashes.",
)


list_path: Callable[..., Option] = partial(
    PipOption,
    "--path",
    dest="path",
    type="path",
    action="append",
    help="Restrict to the specified installation path for listing "
    "packages (can be used multiple times).",
)


def check_list_path_option(options: Values) -> None:
    if options.path and (options.user or options.local):
        raise CommandError("Cannot combine '--path' with '--user' or '--local'")


list_exclude: Callable[..., Option] = partial(
    PipOption,
    "--exclude",
    dest="excludes",
    action="append",
    metavar="package",
    type="package_name",
    help="Exclude specified package from the output",
)


no_python_version_warning: Callable[..., Option] = partial(
    Option,
    "--no-python-version-warning",
    dest="no_python_version_warning",
    action="store_true",

View on GitHub (pinned to f399c37189)