What causes "Can not combine '--user' and '--target'" in pypa/pip?

Choose one: drop --user (use --target alone) or drop --target (use --user alone).

pypa/pip · error · CommandError

Can not combine '--user' and '--target'

Error message

Can not combine '--user' and '--target'

What it means

Raised by `pip install` when both --user and --target are supplied. InstallCommand.run at install.py:373 checks this first because the two flags imply mutually exclusive installation locations (user site-packages vs. an arbitrary target directory).

Solutions

Choose one: drop --user (use --target alone) or drop --target (use --user alone).
For bundling into a local directory use `pip install --target ./libs <pkg>`.
For installing to your user site use `pip install --user <pkg>`.

Example fix

// before
pip install --user --target ./libs numpy
// after
pip install --target ./libs numpy

Defensive patterns

Strategy: validation

Validate before calling

# Reject combining --user and --target before invoking pip install
def install_opts_ok(use_user, target_dir):
    if use_user and target_dir is not None:
        raise ValueError("--user and --target are mutually exclusive")
    return True

Prevention

Never pass both --user and --target in the same invocation.
Centralize install option assembly in one helper that enforces exclusivity.

When it happens

Trigger: Invoking `pip install --user --target ./libs <pkg>` — options.use_user_site is True and options.target_dir is not None, hitting install.py:373-374.

Common situations: User combines flags from different recipes, or scripts assume pip will pick one. Common when migrating a setup from per-user installs to a target-dir layout.

Related errors

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

Appendix: source

Thrown at src/pip/_internal/commands/install.py:374

                "to avoid mixing pip logging output with JSON output."
            ),
        )

    @contextlib.contextmanager
    def pip_version_check(self, options: Values, args: list[str]) -> Iterator[None]:
        # Skip the self-version check when pip itself is a requirement. The
        # running pip may be replaced mid-command, and the upgrade prompt
        # is redundant.
        if any(_arg_refers_to_pip(arg) for arg in args):
            yield
            return
        with super().pip_version_check(options, args):
            yield

    @with_cleanup
    def run(self, options: Values, args: list[str]) -> int:
        if options.use_user_site and options.target_dir is not None:
            raise CommandError("Can not combine '--user' and '--target'")

        # Check whether the environment we're installing into is externally
        # managed, as specified in PEP 668. Specifying --root, --target, or
        # --prefix disables the check, since there's no reliable way to locate
        # the EXTERNALLY-MANAGED file for those cases. An exception is also
        # made specifically for "--dry-run --report" for convenience.
        installing_into_current_environment = (
            not (options.dry_run and options.json_report_file)
            and options.root_path is None
            and options.target_dir is None
            and options.prefix_path is None
        )
        if (
            installing_into_current_environment
            and not options.override_externally_managed
        ):
            check_externally_managed()

View on GitHub (pinned to f399c37189)