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

Remove either --user or --target from the command — decide which destination you actually want.

pypa/pip · error · CommandError

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

Error message

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

What it means

pip raises this CommandError in InstallCommand.run() when both --user and --target (the -t/--target option) are supplied simultaneously. The two flags specify mutually exclusive installation destinations: --user installs to the per-user site-packages directory while --target installs to an arbitrary directory. Because they both dictate where packages are written, pip refuses to guess which one takes precedence.

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

Solutions

Remove either --user or --target from the command — decide which destination you actually want.
If you want packages in a specific directory, drop --user and keep --target <dir> (use --upgrade to refresh existing entries).
If you want a user-level install, drop --target and keep --user.
Check your pip.conf files (global, user, site) for a stray 'user = true' setting that silently combines with your --target flag.

Example fix

# before
pip install --user --target ./libs requests
# after
pip install --target ./libs requests

Defensive patterns

Strategy: validation

Validate before calling

# Validate before invoking pip install
import sys, subprocess

user_flag = '--user' in sys.argv
target_flag = any(a in ('-t','--target') or a.startswith('--target=') for a in sys.argv)
if user_flag and target_flag:
    print('ERROR: --user and --target are mutually exclusive', file=sys.stderr)
    sys.exit(2)

Prevention

Never combine --user with --target/--prefix in scripts; pick one destination explicitly.
Audit pip.conf for 'user = true' before relying on --target.
Wrap pip calls in a validation helper that rejects mutually exclusive flags.

When it happens

Trigger: Invoking pip install with both --user and --target <dir> on the command line, or having 'user = true' in a pip.conf while also passing --target on the CLI. The check at install.py:373 fires immediately when options.use_user_site is truthy and options.target_dir is not None.

Common situations: Copy-pasting a long pip install command from a guide that used --target into an environment where --user is set in a config file; CI scripts that layer --user for non-root installs while also using --target to stage wheels; build tooling (e.g. tox, nox) that injects --target for a staging dir while the user explicitly adds --user.

Related errors

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