{"id":17526939,"url":"https://github.com/bulletmark/pipxu","last_synced_at":"2025-04-22T10:42:15.413Z","repository":{"id":230330893,"uuid":"779118735","full_name":"bulletmark/pipxu","owner":"bulletmark","description":"Install and Run Python Applications in Isolated Environments using UV","archived":false,"fork":false,"pushed_at":"2024-04-12T22:20:46.000Z","size":188,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2024-04-14T10:15:33.300Z","etag":null,"topics":["pip","pipx","python","uv","venv","virtualenv"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bulletmark.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2024-03-29T04:40:18.000Z","updated_at":"2024-04-16T01:34:53.496Z","dependencies_parsed_at":"2024-04-16T01:34:48.896Z","dependency_job_id":null,"html_url":"https://github.com/bulletmark/pipxu","commit_stats":null,"previous_names":["bulletmark/pipxu"],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bulletmark%2Fpipxu","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bulletmark%2Fpipxu/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bulletmark%2Fpipxu/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bulletmark%2Fpipxu/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bulletmark","download_url":"https://codeload.github.com/bulletmark/pipxu/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243318778,"owners_count":20272136,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["pip","pipx","python","uv","venv","virtualenv"],"created_at":"2024-10-20T15:02:38.706Z","updated_at":"2025-03-13T00:37:32.980Z","avatar_url":"https://github.com/bulletmark.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"## PIPXU - Install and Run Python Applications in Isolated Environments using UV\n[![PyPi](https://img.shields.io/pypi/v/pipxu)](https://pypi.org/project/pipxu/)\n[![AUR](https://img.shields.io/aur/version/pipxu)](https://aur.archlinux.org/packages/pipxu/)\n\n[`pipxu`][pipxu] installs Python applications, i.e. Python packages which have\none or more executable programs, into independent isolated virtual environments\non your system. Each package and it's dependencies are thus insulated from all\nother applications, and from the system Python. [`pipxu`][pipxu] creates links\nto application executables in a common directory, e.g. `$HOME/.local/bin` is\ndefault for most Linux users, which you should ensure is in your [PATH][path].\nPackages are typically sourced from [PyPI][pypi], the Python Package Index.\n\n[`pipxu`][pipxu] is a re-implementation of most of the functionality of\nthe popular [`pipx`][pipx] tool but is **much faster** because it uses\n[`uv`][uv] to create and install application virtual environments\ninstead of [`venv`][venv] and [`pip`][pip] as used by [`pipx`][pipx].\nThe [`pipxu`][pipxu] code has been developed completely independently of\n[`pipx`][pipx] and is not a fork. For compatibility and ease of\nmigration, the provided commands have the same names as [`pipx`][pipx].\nMost commands are implemented, at least for common use cases, although\nsome command functionality, options, and output are slightly different.\n\nThis utility has been developed and tested on Linux but will likely also work\non macOS. It does not work and is not supported on Windows. The latest\ndocumentation and code is available at https://github.com/bulletmark/pipxu.\n\n## Usage\n\nType `pipxu` or `pipxu -h` to view the usage summary:\n\n```\nusage: pipxu [-h] [--uv uv_path] [-m] [--home HOME] [--bin-dir BIN_DIR]\n                   [--man-dir MAN_DIR] [--default-python DEFAULT_PYTHON] [-V]\n                   {debug,inject,install,list,reinstall,runpip,uninject,uninstall,remove,upgrade,update,venv,version} ...\n\nInstall Python applications into isolated virtual environments and create\nlinks to the executables in a bin directory for your PATH. Like pipx but uses\nuv instead of venv + pip.\n\noptions:\n  -h, --help            show this help message and exit\n  --uv uv_path          path to uv executable, default=\"uv\"\n  -m, --no-man-pages    do not install package man pages\n  --home HOME           specify PIPXU_HOME\n  --bin-dir BIN_DIR     specify PIPXU_BIN_DIR\n  --man-dir MAN_DIR     specify PIPXU_MAN_DIR\n  --default-python DEFAULT_PYTHON\n                        path to default python executable, default=\"python3\"\n  -V, --version         just print pipxu version and exit\n\nCommands:\n  {debug,inject,install,list,reinstall,runpip,uninject,uninstall,remove,upgrade,update,venv,version}\n    debug               Run an installed application using a debugger.\n    inject              Install extra packages into an application.\n    install             Install one or more Python applications using isolated\n                        virtual environments.\n    list                List applications installed by this tool.\n    reinstall           Reinstall one, or more, or all applications.\n    runpip              Run pip with given arguments on virtual environment\n                        for the given application.\n    uninject            Uninstall extra packages from an application.\n    uninstall (remove)  Uninstall one, or more, or all applications.\n    upgrade (update)    Upgrade one, or more, or all applications.\n    venv                List application virtual environment paths.\n    version             List installed application versions.\n\nSome commands offer aliases as shown in parentheses above. Note you can set\ndefault starting global options in $HOME/.config/pipxu-flags.conf.\n```\n\nType `pipxu \u003ccommand\u003e -h` to see specific help/usage for any\nindividual command:\n\n### Command `debug`\n\n```\nusage: pipxu debug [-h] [-e EXECUTABLE] [-d DEBUGGER] package [args ...]\n\nRun an installed application using a debugger. Tries to work out your\npreferred debugger from the standard PYTHONBREAKPOINT environment variable. If\nnot set it defaults to pdb. Or you can set it explicitly with the\n-d/--debugger option.\n\npositional arguments:\n  package               installed application name\n  args                  options and arguments to pass to application, should\n                        start with \"--\"\n\noptions:\n  -h, --help            show this help message and exit\n  -e, --executable EXECUTABLE\n                        executable to run, default is same as \"package\" name\n  -d, --debugger DEBUGGER\n                        explicit debugger package to use\n```\n\n### Command `inject`\n\n```\nusage: pipxu inject [-h] [-v] package extras [extras ...]\n\nInstall extra packages into an application. Note the same --index-url is used\nas/if specified in the original install.\n\npositional arguments:\n  package        installed application name\n  extras         extra package name[s] to inject/install\n\noptions:\n  -h, --help     show this help message and exit\n  -v, --verbose  give more output\n```\n\n### Command `install`\n\n```\nusage: pipxu install [-h] [-p PYTHON] [-f] [-e] [-d]\n                           [--system-site-packages] [-i INDEX_URL] [-v]\n                           package [package ...]\n\nInstall one or more Python applications using isolated virtual environments.\n\npositional arguments:\n  package               application[s] to install\n\noptions:\n  -h, --help            show this help message and exit\n  -p, --python PYTHON   specify explicit python executable path\n  -f, --force           recreate any already installed venv\n  -e, --editable        install application[s] in editable mode\n  -d, --include-deps    include executables from dependencies\n  --system-site-packages\n                        allow venv access to system packages\n  -i, --index-url INDEX_URL\n                        base URL of Python Package Index\n  -v, --verbose         give more output\n```\n\n### Command `list`\n\n```\nusage: pipxu list [-h] [--json] [-v] [package ...]\n\nList applications installed by this tool.\n\npositional arguments:\n  package     list the given application[s] only\n\noptions:\n  -h, --help  show this help message and exit\n  --json      output json instead\n  -v, --venv  also show the virtual environment dir/number\n```\n\n### Command `reinstall`\n\n```\nusage: pipxu reinstall [-h] [-p PYTHON | --reset-python]\n                             [--system-site-packages |\n                             --no-system-site-packages] [-v] [--all] [--skip]\n                             [package ...]\n\nReinstall one, or more, or all applications.\n\npositional arguments:\n  package               application[s] to reinstall (or to skip for --all\n                        --skip)\n\noptions:\n  -h, --help            show this help message and exit\n  -p, --python PYTHON   specify explicit python executable path\n  --reset-python        reset any explicit python path to default python\n  --system-site-packages\n                        allow venv access to system packages, overrides the\n                        per-application setting\n  --no-system-site-packages\n                        remove venv access to system packages, overrides the\n                        per-application setting\n  -v, --verbose         give more output\n  --all                 reinstall ALL applications\n  --skip                skip the specified applications when reinstalling all\n                        (only can be specified with --all)\n```\n\n### Command `runpip`\n\n```\nusage: pipxu runpip [-h] package [args ...]\n\nRun pip with given arguments on virtual environment for the given application.\n\npositional arguments:\n  package     installed application name\n  args        arguments to pass to uv pip, should start with \"--\".\n\noptions:\n  -h, --help  show this help message and exit\n```\n\n### Command `uninject`\n\n```\nusage: pipxu uninject [-h] [-v] package extras [extras ...]\n\nUninstall extra packages from an application.\n\npositional arguments:\n  package        installed application name\n  extras         extra package name[s] to uninstall\n\noptions:\n  -h, --help     show this help message and exit\n  -v, --verbose  give more output\n```\n\n### Command `uninstall`\n\n```\nusage: pipxu uninstall [-h] [-v] [--all] [--skip] [package ...]\n\nUninstall one, or more, or all applications.\n\npositional arguments:\n  package        application[s] to uninstall (or to skip for --all --skip)\n\noptions:\n  -h, --help     show this help message and exit\n  -v, --verbose  give more output\n  --all          uninstall ALL applications\n  --skip         skip the specified applications when uninstalling all (only\n                 can be specified with --all)\n\naliases: remove\n```\n\n### Command `upgrade`\n\n```\nusage: pipxu upgrade [-h] [-v] [--all] [--skip] [package ...]\n\nUpgrade one, or more, or all applications.\n\npositional arguments:\n  package        application[s] to upgrade (or to skip for --all --skip)\n\noptions:\n  -h, --help     show this help message and exit\n  -v, --verbose  give more output\n  --all          upgrade ALL applications\n  --skip         skip the specified applications when upgrading all (only can\n                 be specified with --all)\n\naliases: update\n```\n\n### Command `venv`\n\n```\nusage: pipxu venv [-h] [-p] [-s] [package ...]\n\nList application virtual environment paths.\n\npositional arguments:\n  package          list the path for the given application[s] rather than all\n                   applications.\n\noptions:\n  -h, --help       show this help message and exit\n  -p, --path-full  don't abbreviate the path\n  -s, --sort-venv  sort by venv path rather than package name\n```\n\n### Command `version`\n\n```\nusage: pipxu version [-h] [package]\n\nList installed application versions.\n\npositional arguments:\n  package     report specific application and dependent package versions\n\noptions:\n  -h, --help  show this help message and exit\n```\n\n## Installation and Upgrade\n\nPython 3.8 or later is required. Arch Linux users can install [`pipxu`\nfrom the AUR](https://aur.archlinux.org/packages/pipxu) and skip this\nsection.\n\nThe [`uv`][uv] program must be installed (and it's version must be\n0.1.33 or later). If [`uv`][uv] is not available via your system\npackages, you can install it by following the [uv installation\ninstructions](https://github.com/astral-sh/uv#getting-started) for your\nplatform.\n\nE.g. For Linux and macOS:\n```sh\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n```\n\nNote [`pipxu` is on PyPI](https://pypi.org/project/pipxu/). With `uv`\ninstalled and on your PATH, run the tiny [bootstrap shell\nscript](https://github.com/bulletmark/pipxu/blob/main/pipxu-bootstrap)\nwhich installs `pipxu` to a temporary directory then runs `pipxu` from\nthere to install itself normally:\n\n```sh\n$ curl -LsSf https://raw.githubusercontent.com/bulletmark/pipxu/main/pipxu-bootstrap | sh\n```\n\nOr install `pipxu` using `pipx` if you prefer:\n\n```sh\n$ pipx install pipxu\n$ pipxu install pipxu\n$ pipx uninstall pipxu\n```\n\nTo upgrade:\n\n```sh\n$ pipxu upgrade pipxu\n```\n\nTo uninstall all `pipxu` installed applications, and then uninstall\n`pipxu` itself:\n\n```sh\n$ pipxu uninstall --all --skip pipxu\n$ pipxu uninstall pipxu\n```\n\n## Recovery\n\nThe `pipxu` package also installs the aforementioned\n[`pipxu-bootstrap`](https://github.com/bulletmark/pipxu/blob/main/pipxu-bootstrap)\nshell script on your system so you can always recover easily from a\nbroken `pipxu` installation by manually running that script. E.g. The\nfollowing may be needed after a major or incompatible Python version\nupgrade where `pipxu` may have stopped working:\n\n```sh\n$ pipxu-bootstrap\n$ pipxu reinstall --all --skip pipxu\n```\n\n## Comparison to pipx\n\nWhy would you use [`pipxu`][pipxu] instead of [`pipx`][pipx]? The main\nreason is to gain a massive speed improvement. `pipx` uses [`python -m\nvenv`][venv] to create and install virtual environments and [`pip`][pip]\nto install packages whereas `pipxu` uses [`uv`][uv] for these\noperations. [`uv`][uv] is [a new project](https://astral.sh/blog/uv)\nwritten in [rust](https://www.rust-lang.org/) which has a better design\nthan [`venv`][venv] + [`pip`][pip], caches aggressively, and is **much\nfaster**. Also, `pipx` installs `pip` into each virtual environment\nusing a shared overlay which it has to update periodically so you\nsometimes experience `pipx` seeming to hang for a while while this\nupdate occurs. `pipxu` just creates a minimal lean virtual environment\nand uses `uv` for all operations so does not need to do this periodic\nupdate.\n\nNote that `pipx` offers some esoteric options and features which `pipxu`\ndoes not have. `pipxu` caters for the common use cases. `pipxu` never\nmodifies your PATH.\n\n`pipxu` adds some small but handy features not present in `pipx`:\n\n1. For the commands `uninstall`, `reinstall`, and `upgrade`, `pipx` only\n   allows you to specify one application whereas `pipxu` allows you to\n   specify one or more applications. To do an operation on **all**\n   applications, `pipx`, requires you use a corresponding `*-all`\n   command, e.g. to `upgrade` all applications you use `upgrade-all`.\n   `pipxu` simply offers a `--all` option on each of those base commands\n   to do the same thing, thus avoiding the need for the extra `*-all`\n   commands. Also, `pipx` also does not offer `--skip` for all those\n   `*-all` commands consistently, whereas `pipxu` does.\n\n2. You can do `pipxu` commands on an editable projects (as often used by\n   developers) in your project directory by simply typing \"`.`\" as the\n   package name and this works for all commands. E.g. `pipxu uninstall\n   .` or `pipxu inject . pudb`. I.e. `pipxu` automatically determines\n   the package name associated with the current directory, or any child\n   directories. Note that `pipx` accepts \"`.`\" for the install command,\n   but not for any others.\n\n3. For Python developers,`pipxu` adds a [`debug`](#command-debug)\n   command to conveniently run an installed application using a\n   debugger. `pipx` does not have this command. Read more about the\n   `debug` command [here](doc/debug.md).\n\n4. If run as root or with `sudo`, `pipxu` installs applications to a\n   global location.\n\n## Environment Variables\n\nType `pipxu` without any arguments to see usage and the current\nenvironment. The environment is printed at the bottom of the screen\noutput as follows:\n\nE.g. run as my user \"mark\":\n\n```\nEnvironment:\nPIPXU_HOME = /home/mark/.local/share/pipxu\nPIPXU_BIN_DIR = /home/mark/.local/bin\nPIPXU_MAN_DIR = /home/mark/.local/share/man\nPIPXU_DEFAULT_PYTHON = python3\n\nYour PATH contains PIPXU_BIN_DIR (/home/mark/.local/bin).\n```\n\nOr run as root, or with [`sudo`](https://www.sudo.ws/):\n\n```\nEnvironment:\nPIPXU_HOME = /opt/pipxu\nPIPXU_BIN_DIR = /usr/local/bin\nPIPXU_MAN_DIR = /usr/local/share/man\nPIPXU_DEFAULT_PYTHON = python3\n\nWARNING: Your PATH does not contain PIPXU_BIN_DIR (/usr/local/bin).\n```\n\nYou can set those environment variables, or provide them as command line\noptions, to override the defaults if you want. Note, as seen in the\noutput above, `pipxu` reports if `PIPXU_BIN_DIR` is included or not in\nyour PATH. To ensure you can run the applications installed by `pipxu`,\nthat directory **must be in your PATH**. E.g. for most users on Linux\nusing the default locations, ensure that `~/.local/bin` is [added to\nyour PATH environment variable][path].\n\n## Command Default Options\n\nYou can add default global options to a personal configuration file\n`~/.config/pipxu-flags.conf`. If that file exists then each line of\noptions will be concatenated and automatically prepended to your `pipxu`\ncommand line arguments. Comments in the file (i.e. `#` and anything\nafter on a line) are ignored. Type `pipxu` to see all supported options.\n\nThe global options: `--uv`, `--no-man-pages`, `--home`, `--bin-dir`,\n`--man-dir`, `--default-python`, are the only sensible candidates to\nconsider setting as defaults.\n\n## Command Line Tab Completion\n\nCommand line shell [tab\ncompletion](https://en.wikipedia.org/wiki/Command-line_completion) is\nautomatically enabled on `pipxu` commands and options using\n[`argcomplete`](https://github.com/kislyuk/argcomplete). You may need to\nfirst (once-only) [activate argcomplete global\ncompletion](https://github.com/kislyuk/argcomplete#global-completion).\n\n## License\n\nCopyright (C) 2024 Mark Blakeney. This program is distributed under the\nterms of the GNU General Public License. This program is free software:\nyou can redistribute it and/or modify it under the terms of the GNU\nGeneral Public License as published by the Free Software Foundation,\neither version 3 of the License, or any later version. This program is\ndistributed in the hope that it will be useful, but WITHOUT ANY\nWARRANTY; without even the implied warranty of MERCHANTABILITY or\nFITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License at\n\u003chttp://www.gnu.org/licenses/\u003e for more details.\n\n[pipxu]: https://github.com/bulletmark/pipxu\n[pipx]: https://github.com/pypa/pipx\n[uv]: https://github.com/astral-sh/uv\n[venv]: https://docs.python.org/3/library/venv.html\n[pip]: https://pip.pypa.io/en/stable/\n[pypi]: https://pypi.org/\n[path]: https://www.baeldung.com/linux/path-variable\n\n\u003c!-- vim: se ai syn=markdown: --\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbulletmark%2Fpipxu","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbulletmark%2Fpipxu","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbulletmark%2Fpipxu/lists"}