1PIPX(1)                     General Commands Manual                    PIPX(1)
2
3
4

NAME

6       pipx - Install and execute apps from Python packages.
7

SYNOPSIS

9       pipx    [-h]    [--version]   {install,inject,upgrade,upgrade-all,unin‐
10       stall,uninstall-all,reinstall,reinstall-all,list,run,runpip,en‐
11       surepath,environment,completions} ...
12

DESCRIPTION

14       Install and execute apps from Python packages.
15
16       Binaries  can  either be installed globally into isolated Virtual Envi‐
17       ronments or run directly in a temporary Virtual Environment.
18
19       Virtual Environment location is ~/.local/pipx/venvs.  Symlinks to  apps
20       are placed in ~/.local/bin.
21
22       optional environment variables:
23         PIPX_HOME              Overrides default pipx location. Virtual Envi‐
24       ronments
25                               will be installed to $PIPX_HOME/venvs.
26         PIPX_BIN_DIR          Overrides location of app  installations.  Apps
27       are
28                               symlinked or copied here.
29         PIPX_DEFAULT_PYTHON   Overrides default python used for commands.
30         USE_EMOJI              Overrides emoji behavior. Default value varies
31       based
32                               on platform.
33
34

OPTIONS

36       --version
37              Print version and exit
38
39

SUBCOMMANDS

41       pipx install
42              Install a package
43
44       pipx inject
45              Install packages into an existing Virtual Environment
46
47       pipx upgrade
48              Upgrade a package
49
50       pipx upgrade-all
51              Upgrade all packages. Runs `pip install -U <pkgname>`  for  each
52              package.
53
54       pipx uninstall
55              Uninstall a package
56
57       pipx uninstall-all
58              Uninstall all packages
59
60       pipx reinstall
61              Reinstall a package
62
63       pipx reinstall-all
64              Reinstall all packages
65
66       pipx list
67              List installed packages
68
69       pipx run
70              Download  the latest version of a package to a temporary virtual
71              environment, then run an app from it. Also compatible with local
72              `__pypackages__` directory (experimental).
73
74       pipx runpip
75              Run pip in an existing pipx-managed Virtual Environment
76
77       pipx ensurepath
78              Ensure directories necessary for pipx operation are in your PATH
79              environment variable.
80
81       pipx environment
82              Print a list of variables used in pipx.constants.
83
84       pipx completions
85              Print instructions on enabling shell completions for pipx
86

COMMAND 'pipx install'

88       usage: pipx install [-h] [--include-deps] [--verbose] [--force]
89                           [--suffix SUFFIX] [--python PYTHON]
90                           [--system-site-packages] [--index-url INDEX_URL]
91                           [--editable] [--pip-args PIP_ARGS]
92                           package_spec
93
94       The install command is the preferred way to globally install apps  from
95       python packages on your system. It creates an isolated virtual environ‐
96       ment for the package, then ensures the package's apps are accessible on
97       your $PATH.
98
99       The result: apps you can run from anywhere, located in packages you can
100       cleanly upgrade or uninstall. Guaranteed to not have dependency version
101       conflicts  or  interfere  with your OS's python packages. 'sudo' is not
102       required to do this.
103
104       pipx install PACKAGE_NAME pipx  install  --python  PYTHON  PACKAGE_NAME
105       pipx  install  VCS_URL  pipx install ./LOCAL_PATH pipx install ZIP_FILE
106       pipx install TAR_GZ_FILE
107
108       The PACKAGE_SPEC argument is passed directly to `pip install`.
109
110       The default virtual environment location is ~/.local/pipx  and  can  be
111       overridden by setting the environment variable `PIPX_HOME` (Virtual En‐
112       vironments will be installed to `$PIPX_HOME/venvs`).
113
114       The default app location is ~/.local/bin and can be overridden by  set‐
115       ting the environment variable `PIPX_BIN_DIR`.
116
117       The   default   python   executable   used  to  install  a  package  is
118       /usr/bin/python3 and can be overridden by setting the environment vari‐
119       able `PIPX_DEFAULT_PYTHON`.
120
121
122       package_spec
123              package name or pip installation spec
124
125

OPTIONS 'pipx install'

127       --include-deps
128              Include apps of dependent packages
129
130
131       --verbose
132
133       --force, -f
134              Modify existing virtual environment and files in PIPX_BIN_DIR
135
136
137       --suffix SUFFIX
138              Optional  suffix  for  virtual environment and executable names.
139              NOTE: The suffix feature is experimental and subject to change.
140
141
142       --python PYTHON
143              The Python executable used to create the Virtual Environment and
144              run the associated app/apps. Must be v3.6+.
145
146
147       --system-site-packages
148              Give  the virtual environment access to the system site-packages
149              dir.
150
151
152       --index-url INDEX_URL, -i INDEX_URL
153              Base URL of Python Package Index
154
155
156       --editable, -e
157              Install a project in editable mode
158
159
160       --pip-args PIP_ARGS
161              Arbitrary pip arguments to pass directly to pip  install/upgrade
162              commands
163
164

COMMAND 'pipx inject'

166       usage: pipx inject [-h] [--include-apps] [--include-deps]
167                          [--system-site-packages] [--index-url INDEX_URL]
168                          [--editable] [--pip-args PIP_ARGS] [--force] [--ver‐
169       bose]
170                          package dependencies [dependencies ...]
171
172       Installs packages to an existing pipx-managed virtual environment.
173
174
175       package
176              Name of the existing pipx-managed Virtual Environment to  inject
177              into
178
179
180       dependencies
181              the  packages  to  inject  into  the Virtual Environment--either
182              package name or pip package spec
183
184

OPTIONS 'pipx inject'

186       --include-apps
187              Add apps from the injected packages onto your PATH
188
189
190       --include-deps
191              Include apps of dependent packages
192
193
194       --system-site-packages
195              Give the virtual environment access to the system  site-packages
196              dir.
197
198
199       --index-url INDEX_URL, -i INDEX_URL
200              Base URL of Python Package Index
201
202
203       --editable, -e
204              Install a project in editable mode
205
206
207       --pip-args PIP_ARGS
208              Arbitrary  pip arguments to pass directly to pip install/upgrade
209              commands
210
211
212       --force, -f
213              Modify existing virtual environment and files in PIPX_BIN_DIR
214
215
216       --verbose
217

COMMAND 'pipx upgrade'

219       usage: pipx upgrade [-h] [--include-injected] [--force]
220                           [--system-site-packages] [--index-url INDEX_URL]
221                           [--editable] [--pip-args PIP_ARGS] [--verbose]
222                           package
223
224       Upgrade a package in a pipx-managed Virtual Environment by running 'pip
225       install --upgrade PACKAGE'
226
227
228       package
229

OPTIONS 'pipx upgrade'

231       --include-injected
232              Also upgrade packages injected into the main app's environment
233
234
235       --force, -f
236              Modify existing virtual environment and files in PIPX_BIN_DIR
237
238
239       --system-site-packages
240              Give  the virtual environment access to the system site-packages
241              dir.
242
243
244       --index-url INDEX_URL, -i INDEX_URL
245              Base URL of Python Package Index
246
247
248       --editable, -e
249              Install a project in editable mode
250
251
252       --pip-args PIP_ARGS
253              Arbitrary pip arguments to pass directly to pip  install/upgrade
254              commands
255
256
257       --verbose
258

COMMAND 'pipx upgrade-all'

260       usage:  pipx  upgrade-all  [-h] [--include-injected] [--skip SKIP [SKIP
261       ...]]
262                               [--force] [--verbose]
263
264       Upgrades all packages within their virtual environments by running 'pip
265       install --upgrade PACKAGE'
266
267

OPTIONS 'pipx upgrade-all'

269       --include-injected
270              Also upgrade packages injected into the main app's environment
271
272
273       --skip SKIP [SKIP ...]
274              skip these packages
275
276
277       --force, -f
278              Modify existing virtual environment and files in PIPX_BIN_DIR
279
280
281       --verbose
282

COMMAND 'pipx uninstall'

284       usage: pipx uninstall [-h] [--verbose] package
285
286       Uninstalls  a  pipx-managed  Virtual Environment by deleting it and any
287       files that point to its apps.
288
289
290       package
291

OPTIONS 'pipx uninstall'

293       --verbose
294

COMMAND 'pipx uninstall-all'

296       usage: pipx uninstall-all [-h] [--verbose]
297
298       Uninstall all pipx-managed packages
299
300

OPTIONS 'pipx uninstall-all'

302       --verbose
303

COMMAND 'pipx reinstall'

305       usage: pipx reinstall [-h] [--python PYTHON] [--verbose] package
306
307       Reinstalls a package.
308
309       Package is uninstalled, then installed with pipx install  PACKAGE  with
310       the same options used in the original install of PACKAGE.
311
312
313       package
314

OPTIONS 'pipx reinstall'

316       --python PYTHON
317              The  Python  executable used to recreate the Virtual Environment
318              and run the associated app/apps. Must be v3.6+.
319
320
321       --verbose
322

COMMAND 'pipx reinstall-all'

324       usage: pipx reinstall-all [-h] [--python  PYTHON]  [--skip  SKIP  [SKIP
325       ...]]
326                                 [--verbose]
327
328       Reinstalls all packages.
329
330       Packages are uninstalled, then installed with pipx install PACKAGE with
331       the same options used in the original install of PACKAGE.  This is use‐
332       ful  if you upgraded to a new version of Python and want all your pack‐
333       ages to use the latest as well.
334
335

OPTIONS 'pipx reinstall-all'

337       --python PYTHON
338              The Python executable used to recreate the  Virtual  Environment
339              and run the associated app/apps. Must be v3.6+.
340
341
342       --skip SKIP [SKIP ...]
343              skip these packages
344
345
346       --verbose
347

COMMAND 'pipx list'

349       usage:  pipx  list [-h] [--include-injected] [--json | --short] [--ver‐
350       bose]
351
352       List packages and apps installed with pipx
353
354

OPTIONS 'pipx list'

356       --include-injected
357              Show packages injected into the main app's environment
358
359
360       --json Output rich data in json format.
361
362
363       --short
364              List packages only.
365
366
367       --verbose
368

COMMAND 'pipx run'

370       usage: pipx run [-h] [--no-cache] [--pypackages] [--spec SPEC]  [--ver‐
371       bose]
372                       [--python PYTHON] [--system-site-packages]
373                       [--index-url    INDEX_URL]   [--editable]   [--pip-args
374       PIP_ARGS]
375                       app ...
376
377       Download the latest version of a package to a temporary  virtual  envi‐
378       ronment,  then  run  an app from it. The environment will be cached and
379       re-used for up to 14 days. This means subsequent calls to 'run' for the
380       same  package  will  be faster since they can re-use the cached Virtual
381       Environment.
382
383       In support of PEP 582 'run' will use apps found in  a  local  __pypack‐
384       ages__ directory, if present. Please note that this behavior is experi‐
385       mental, and acts as a companion tool to pythonloc. It may  be  modified
386       or removed in the future. See https://github.com/cs01/pythonloc.
387
388
389       app ...
390              app/package name and any arguments to be passed to it
391
392

OPTIONS 'pipx run'

394       --no-cache
395              Do not re-use cached virtual environment if it exists
396
397
398       --pypackages
399              Require app to be run from local __pypackages__ directory
400
401
402       --spec SPEC
403              The  package name or specific installation source passed to pip.
404              Runs  `pip  install  -U  SPEC`.   For  example  `--spec  mypack‐
405              age==2.0.0`                      or                      `--spec
406              git+https://github.com/user/repo.git@branch`
407
408
409       --verbose
410
411       --python PYTHON
412              The Python version to run package's CLI app with. Must be v3.6+.
413
414
415       --system-site-packages
416              Give the virtual environment access to the system  site-packages
417              dir.
418
419
420       --index-url INDEX_URL, -i INDEX_URL
421              Base URL of Python Package Index
422
423
424       --editable, -e
425              Install a project in editable mode
426
427
428       --pip-args PIP_ARGS
429              Arbitrary  pip arguments to pass directly to pip install/upgrade
430              commands
431
432

COMMAND 'pipx runpip'

434       usage: pipx runpip [-h] [--verbose] package ...
435
436       Run pip in an existing pipx-managed Virtual Environment
437
438
439       package
440              Name of the existing pipx-managed Virtual Environment to run pip
441              in
442
443
444       pipargs
445              Arguments to forward to pip command
446
447

OPTIONS 'pipx runpip'

449       --verbose
450

COMMAND 'pipx ensurepath'

452       usage: pipx ensurepath [-h] [--force]
453
454       Ensure  directory  where  pipx  stores apps is in your PATH environment
455       variable. Also if pipx was installed via `pip install  --user`,  ensure
456       pipx  itself  is  in  your PATH. Note that running this may modify your
457       shell's configuration file(s) such as '~/.bashrc'.
458
459

OPTIONS 'pipx ensurepath'

461       --force, -f
462              Add text to your shell's config file even if it looks like  your
463              PATH already contains paths to pipx and pipx-install apps.
464
465

COMMAND 'pipx environment'

467       usage: pipx environment [-h] [--value VARIABLE]
468
469       Available   variables:   PIPX_HOME,   PIPX_BIN_DIR,   PIPX_SHARED_LIBS,
470       PIPX_LOCAL_VENVS, PIPX_LOG_DIR, PIPX_TRASH_DIR, PIPX_VENV_CACHEDIR
471
472       Only PIPX_HOME and PIPX_BIN_DIR can be set by users in the above list.
473
474

OPTIONS 'pipx environment'

476       --value VARIABLE, -v VARIABLE
477              Print the value of the variable.
478
479

COMMAND 'pipx completions'

481       usage: pipx completions [-h]
482
483       Print instructions on enabling shell completions for pipx
484
485

AUTHORS

487       pipx(1) was written by Chad Smith and contributors.  The project can be
488       found online at ⟨https://pypa.github.io/pipx/
489

SEE ALSO

491       pip(1), virtualenv(1)
492
493
494
495                                    Manual                             PIPX(1)
Impressum