pypa/pip · error · CommandError

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

Error message

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

What it means

Raised by check_list_path_option() in cmdoptions.py:1289 when `pip list` is called with --path together with either --user or --local. These are mutually exclusive scope filters: --path restricts to a specific directory, while --user and --local restrict to the user site and current environment respectively. Combining them is ambiguous.

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 d7d0d0a394)

Solutions

1. Use only --path to list packages in a specific directory: `pip list --path ./libs`.
2. Use only --user to list user-site packages: `pip list --user`.
3. Use only --local to list packages in the current environment: `pip list --local`.
4. Run separate pip list commands for each scope if you need to check multiple locations.

Example fix

# before
pip list --path ./libs --user

# after
pip list --path ./libs
# or separately:
pip list --user

def validate_list_path_options(options):
    """Ensure --path is not combined with --user or --local."""
    if options.get('path') and (options.get('user') or options.get('local')):
        return False
    return True

from pip._internal.exceptions import CommandError
try:
    # pip list --path ... --user
except CommandError as e:
    if "'--path'" in str(e):
        # remove --user or --local and retry

When it happens

Trigger: Calling `pip list --path ./libs --user` or `pip list --path ./libs --local` or `pip list --path ./libs --user --local`.

Common situations: Scripts that combine pip list flags indiscriminately. Debugging package installations across multiple locations and trying to narrow scope in multiple ways at once. Shell aliases that always include --user.

Related errors

• Cannot use '--only-dependencies' in combination with {confli
• When restricting platform and interpreter constraints using
• Can not use any platform or abi specific options unless inst
• Platform and interpreter constraints using --python-version,
• --build-constraint cannot be used with --no-build-isolation.

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