Skip to content

Clarify --target behavior with --upgrade#13807

Open
gcomneno wants to merge 1 commit intopypa:mainfrom
gcomneno:docs/clarify-target-upgrade
Open

Clarify --target behavior with --upgrade#13807
gcomneno wants to merge 1 commit intopypa:mainfrom
gcomneno:docs/clarify-target-upgrade

Conversation

@gcomneno
Copy link
Contributor

This updates the help text for pip install --target to clarify that it is intended for use with an empty directory, and that --upgrade does not reliably uninstall or replace packages already present in the target directory.

Closes #13763
Related: #9605, #11366

@pfmoore
Copy link
Member

pfmoore commented Feb 17, 2026

I'd like other maintainers' views here as well, before we merge - we're making it "official" that using --upgrade with --target is unsupported, and that may be viewed as a deprecation (although in my view it's not, as I don't believe the existing implementation is reliable, and as far as I'm aware we've never made any real effort to fix it).

@gcomneno
Copy link
Contributor Author

Thanks! This is intended as a documentation/help clarification only (no behavioral change). I’m happy to tweak wording if maintainers would prefer framing it as “not reliably supported” rather than “unsupported”.

@notatallshaw
Copy link
Member

See also recent related pr #13766

@notatallshaw notatallshaw added the skip news Does not need a NEWS file entry (eg: trivial changes) label Feb 17, 2026
@gcomneno
Copy link
Contributor Author

Thanks — I’ve taken a look at #13766. Happy to align wording between the CLI help and docs/examples so the --target guidance is consistent (especially around empty dirs / --upgrade expectations).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

skip news Does not need a NEWS file entry (eg: trivial changes)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

pip install --target --upgrade does not replace existing package versions

3 participants

Comments