@@ -66,12 +66,118 @@ man pages][netrc-docs].
6666## Keyring Support
6767
6868pip supports loading credentials stored in your keyring using the
69- {pypi}` keyring ` library.
69+ {pypi}` keyring ` library which can be enabled py passing ` --keyring-provider `
70+ with a value of ` auto ` , ` disabled ` , ` import ` or ` subprocess ` . The default value
71+ is ` auto ` . ` auto ` will respect ` --no-input ` and not query keyring at all if that
72+ option is used. The ` auto ` provider will use the ` import ` provider if the
73+ ` keyring ` module can be imported. If that is not the case it will use the
74+ ` subprocess ` provider if a ` keyring ` executable can be found. Otherwise, the
75+ ` disabled ` provider will be used.
76+
77+ ### Configuring Pip
78+ Passing this as a command line argument will work, but is not how the majority
79+ of this feature's users will use it. They instead will want to overwrite the
80+ default of ` disabled ` in the global, user of site configuration file:
81+ ``` bash
82+ $ pip config set --global global.keyring-provider subprocess
83+
84+ # A different user on the same system which has PYTHONPATH configured and and
85+ # wanting to use keyring installed that way could then run
86+ $ pip config set --user global.keyring-provider import
87+
88+ # For a specific virtual environment you might want to use disable it again
89+ # because you will only be using PyPI and the private repo (and mirror)
90+ # requires 2FA with a keycard and a pincode
91+ $ pip config set --site global.index https://pypi.org/simple
92+ $ pip config set --site global.keyring-provider disabled
93+
94+ # configuring it via environment variable is also possible
95+ $ export PIP_KEYRING_PROVIDER=disabled
96+ ```
97+
98+ ### Installing and using the keyring python module
99+
100+ Setting it to ` import ` tries to communicate with ` keyring ` by importing it
101+ and using its Python api.
70102
71103``` bash
72- $ pip install keyring # install keyring from PyPI
104+ # install keyring from PyPI
105+ $ pip install keyring --index-url https://pypi.org/simple
73106$ echo " your-password" | keyring set pypi.company.com your-username
74- $ pip install your-package --index-url https://pypi.company.com/
107+ $ pip install your-package --keyring-provider import --index-url https://pypi.company.com/
108+ ```
109+
110+ ### Installing and using the keyring cli application
111+
112+ Setting it to ` subprocess ` will look for a ` keyring ` executable on the PATH
113+ if one can be found that is different from the ` keyring ` installation ` import `
114+ would be using.
115+
116+ The cli requires a username, therefore you MUST put a username in the url.
117+ See the example below or the basic HTTP authentication section at the top of
118+ this page.
119+
120+ ``` bash
121+ # install keyring from PyPI using pipx, which we assume if installed properly
122+ # you can also create a venv somewhere and add it to the PATH yourself instead
123+ $ pipx install keyring --index-url https://pypi.org/simple
124+
125+ # install the keyring backend for Azure DevOps for example
126+ # VssSessionToken is the username you MUST use for this backend
127+ $ pipx inject keyring artifacts-keyring --index-url https://pypi.org/simple
128+
129+ # or the one for Google Artifact Registry
130+ $ pipx inject keyring keyrings.google-artifactregistry-auth --index-url https://pypi.org/simple
131+ $ gcloud auth login
132+
133+ $ pip install your-package --keyring-provider subprocess --index-url https://
[email protected] /
134+ ```
135+
136+ ### Here be dragons
137+
138+ The ` auto ` provider is conservative and does not query keyring at all when
139+ ` --no-input ` is used because the keyring might require user interaction such as
140+ prompting the user on the console. Third party tools frequently call Pip for
141+ you and do indeed pass ` --no-input ` as they are well-behaved and don't have
142+ much information to work with. (Keyring does have an api to request a backend
143+ that does not require user input.) You have more information about your system,
144+ however!
145+
146+ You can force keyring usage by requesting a keyring provider other than ` auto `
147+ (or ` disabled ` ). Leaving ` import ` and ` subprocess ` . You do this by passing
148+ ` --keyring-provider import ` or one of the following methods:
149+
150+ ``` bash
151+ # via config file, possibly with --user, --global or --site
152+ $ pip config set global.keyring-provider subprocess
153+ # or via environment variable
154+ $ export PIP_KEYRING_PROVIDER=import
155+ ```
156+
157+ ``` {warning}
158+ Be careful when doing this since it could cause tools such as Pipx and Pipenv
159+ to appear to hang. They show their own progress indicator while hiding output
160+ from the subprocess in which they run Pip. You won't know whether the keyring
161+ backend is waiting the user input or not in such situations.
162+ ```
163+
164+ Pip is conservative and does not query keyring at all when ` --no-input ` is used
165+ because the keyring might require user interaction such as prompting the user
166+ on the console. You can force keyring usage by passing ` --force-keyring ` or one
167+ of the following:
168+
169+ ``` bash
170+ # possibly with --user, --global or --site
171+ $ pip config set global.force-keyring true
172+ # or
173+ $ export PIP_FORCE_KEYRING=1
174+ ```
175+
176+ ``` {warning}
177+ Be careful when doing this since it could cause tools such as Pipx and Pipenv
178+ to appear to hang. They show their own progress indicator while hiding output
179+ from the subprocess in which they run Pip. You won't know whether the keyring
180+ backend is waiting the user input or not in such situations.
75181```
76182
77183Note that ` keyring ` (the Python package) needs to be installed separately from
0 commit comments