Add pip completion documentation

[sepehr-rs]

Fixes #13536

[sepehr-rs]

Hi @notatallshaw,
I tried fixing the pre-commit issue, but it’s still showing the same error. Could you please take a closer look at the files and see if you can fix it? Thanks so much! :)

[sepehr-rs]

Hi @notatallshaw, just checking in, do you have any updates on this?

[notatallshaw]

I've checked out locally and reproduced the CI errors, I've added comments to help, let me know if you need me to push these commits or if you can handle it.

[sepehr-rs]

Thanks a lot for the feedback!
I’ll work on fixing these issues, would love your feedback again once I push the updates.

[sepehr-rs]

pre-commit.ci autofix

[sepehr-rs]

Hi @notatallshaw, any updates?

[notatallshaw]

I've never used this feature and am unfamiliar with how to use it.

Just reading the docs you've added: https://pip--13542.org.readthedocs.build/en/13542/cli/pip_completion/ I still don't know how to use this feature.

The feature outputs some code to the stdout, and then what? What am I supposed to do with that? Or is the command doing something else?

[sepehr-rs]

pip completion is supposed to provide the user with a script to enable autocompletion. Typically, users set it up by adding something like this to their shell configuration file (e.g. .bashrc, .zshrc, etc.):

eval "$(pip completion --bash)"
# or
eval "$(pip completion --zsh)"

That way, the shell sources the completion code on startup.

[pfmoore]

I think the point here is that if we're going to document this, we need to include enough information for people who aren't familiar with how completion works to set it up "from scratch". That's going to involve having shell-specific instructions for all the shells we support.

[notatallshaw]

we need to include enough information for people who aren't familiar with how completion works to set it up "from scratch".

Yes exactly, I don't find the current "Examples" section particularly helpful, I would rather see "Example Setups" for each shell supported, so for the Bash example I would prefer to see something like:

echo 'eval "$(pip completion --bash)"' >> ~/.bashrc

If that's a way to add it to Bash.

[sepehr-rs]

Hi @notatallshaw and @pfmoore,
Thank you both for your feedback, really appreciate it.
I’ve updated the documentation to reflect your suggestions and would love to hear your thoughts on the changes.

[pfmoore]

Hmm, I tried the Powershell instructions, and it doesn't work. pip ins<TAB> doesn't complete the install command.

I may be doing something wrong, but to be honest that's the whole point, the instructions need to explain to someone like me who doesn't know what to do, how to get a working setup.

[pfmoore]

I don't know whether it's relevant, but I seem to have both a TabExpansion and a TabExpansion2 function defined...

[notatallshaw]

Yeah, I am also unable to help right now, I tried both the powershell and bash completion instructions and was unable to get either working, I tried debugging for 5 mins with ChatGPT to zero avail.

[sepehr-rs]

Hi @notatallshaw and @pfmoore, thanks a lot for your feedback.

I may be doing something wrong, but to be honest that's the whole point, the instructions need to explain to someone like me who doesn't know what to do, how to get a working setup.
I don't know whether it's relevant, but I seem to have both a TabExpansion and a TabExpansion2 function defined...

I tried this on a Windows machine and after running (Get-Command TabExpansion).Definition I noticed that the script looks for C:\Users\<user>\AppData\Local\Programs\Python\Python313\python.exe -m pip instead of pip. This happens because of how PATHs and pip launchers work on Windows. I've added a small note about it in the documentation. I’m not sure whether it would be helpful to go further and include instructions for users to fix it, or if the note I added is sufficient.

Yeah, I am also unable to help right now, I tried both the powershell and bash completion instructions and was unable to get either working, I tried debugging for 5 mins with ChatGPT to zero avail.

For Bash, the instructions worked for me as expected. I’m sorry I can’t provide a definitive solution; something in your environment may be overriding completion, or you may be encountering the same Windows launcher issue as @pfmoore.

[pfmoore]

I don’t think the docs should be trying to help the user to debug issues, we should be giving instructions that don’t need debugging. If the problem is that the completion script is broken, then we need to fix that, but that’s a separate matter.

Even if others disagree with the above, the suggestions make no sense to me. I don’t have a conventional pip.exe, as I use the zipapp distribution of pip. And I have no idea what Register-ArgumentCompleter is, or how to use it. Finally, I’d expect completion to work no matter how I invoke pip (pip, py -m pip, Python -m pip, …) and your instructions suggest that it depends on the specific command I type.

[sepehr-rs]

I’ll admit I’m a bit lost on how to move this forward right now. Thank you for the detailed feedback so far. It’s clear the docs still aren’t in a state where they’re truly “drop-in” usable.

From what I can tell, the main culprit is that the pip completion script itself doesn’t work consistently, regardless of how pip is invoked (python -m pip, py -m pip, or pip). In my testing, it also doesn’t reliably work in Bash. I’ve attached a video below showing what I’m seeing.

Screencast.From.2025-09-23.11-44-41.mp4

If we can fix the script to handle these cases, then users shouldn’t need to take extra steps to get pip completion working. One possible approach could be to make the script support all common launchers (pip, python -m pip, py -m pip, etc.).
Thanks again for all your help and patience!

[pfmoore]

I agree that step 1 should be to get completion working. Given how many different shells there are, and how many different ways there are to invoke pip, that’s likely to be a significant challenge on its own. But if completion isn’t robust and reliable, documenting how to set it up (and hence increasing the visibility of it) is likely to just result in more support work dealing with issues from users frustrated because it doesn’t work as advertised.

[sepehr-rs]

Given how many different shells there are, and how many different ways there are to invoke pip, that’s likely to be a significant challenge on its own. But if completion isn’t robust and reliable, documenting how to set it up (and hence increasing the visibility of it) is likely to just result in more support work dealing with issues from users frustrated because it doesn’t work as advertised.

I agree, but I’m not sure how to move forward. Do you have any ideas?

[pfmoore]

I've raised #13593 regarding registering completions for the wrong command. And there is already #13577 covering the fact that Powershell completion is broken on current versions of Powershell. Maybe if someone works on those and produces something that can be tested which actually works immediately when maintainers try to review it, then we can move forward.

But to be perfectly honest, I think we'd be better just ripping out completion support. I'm not convinced that it's fixable given the limitations of how shells do completion (which appears to be that you register a completion for a very precise prefix string typed on the command line, rather than being based on what application will ultimately be invoked). I don't think that the minor convenience of tab-completing pip subcommands justifies the complexity and fragility of the feature.

I assume that some people like it, though, so leaving it in, warts and all, is probably less disruptive. I'm not motivated to try to "fix" it or document it better, though, as I don't think we can do a good enough job for such changes to be a net benefit.