Install and Run Python Applications in Isolated Environments using UV
Project description
PIPXU - Install and Run Python Applications in Isolated Environments using UV
pipxu
installs Python applications, i.e. a Python packages
which have one or more executable programs, into independent isolated
virtual environments on your system. Each package and it's dependencies
are thus insulated from all other applications, and from the system
Python. pipxu
creates links to application executables in a
common directory, which you have in your PATH. Packages are
typically sourced from PyPI, the Python Package Index.
pipxu
is a re-implementation of most of the functionality of
the popular pipx
tool but is much faster because it uses
uv
to create and install application virtual environments
instead of venv
and pip
as used by pipx
.
The pipxu
code has been developed completely independently of
pipx
and is not a fork. For compatibility and ease of
migration, the provided commands have the same names as pipx
.
Most commands are implemented, at least for common use cases, although
some command functionality, options, and output are slightly different.
This utility has been developed and tested on Linux. It may work on other platforms, such as Windows and macOS, but has not been tried there. The latest documentation and code is available at https://github.com/bulletmark/pipxu.
Usage
Type pipxu
or pipxu -h
to view the usage summary:
usage: pipxu [-h] [--uv uv_path] [-m] [--home HOME] [--bin-dir BIN_DIR]
[--man-dir MAN_DIR] [--default-python DEFAULT_PYTHON] [-V]
{debug,inject,install,list,reinstall-all,reinstall,runpip,uninject,uninstall-all,uninstall,upgrade-all,upgrade,version}
...
Install Python applications into isolated virtual environments and create
links to the executables in a bin directory for your PATH. Like pipx but uses
uv instead of venv + pip.
options:
-h, --help show this help message and exit
--uv uv_path path to uv executable, default="uv"
-m, --no-man-pages do not install package man pages
--home HOME specify PIPXU_HOME
--bin-dir BIN_DIR specify PIPXU_BIN_DIR
--man-dir MAN_DIR specify PIPXU_MAN_DIR
--default-python DEFAULT_PYTHON
path to default python executable, default="python3"
-V, --version just print pipxu version and exit
Commands:
{debug,inject,install,list,reinstall-all,reinstall,runpip,uninject,uninstall-all,uninstall,upgrade-all,upgrade,version}
debug Run an installed application using a debugger.
inject Install extra packages into an application.
install Install a Python application using an isolated virtual
environment.
list List all applications installed by this tool.
reinstall-all Reinstall all applications.
reinstall Reinstall an application.
runpip Run pip with given arguments on virtual environment
for the given application.
uninject Uninstall extra packages from an application.
uninstall-all Uninstall all applications.
uninstall Uninstall an application.
upgrade-all Upgrade all applications.
upgrade Upgrade an application.
version List installed application versions.
Note you can set default starting global options in $HOME/.config/pipxu-
flags.conf.
Type pipxu <command> -h
to see specific help/usage for any
individual command:
Command debug
usage: pipxu debug [-h] [-e EXECUTABLE] [-d DEBUGGER] package [args ...]
Run an installed application using a debugger.
Tries to work out your preferred debugger from the PYTHONBREAKPOINT
environment variable. If not set, defaults to pdb. Or you can set it
explicitly with the -d/--debugger option.
positional arguments:
package installed application name
args options and arguments to pass to application. should
start with "--".
options:
-h, --help show this help message and exit
-e EXECUTABLE, --executable EXECUTABLE
executable to run, default is same as "package" name
-d DEBUGGER, --debugger DEBUGGER
explicit debugger package to use
Command inject
usage: pipxu inject [-h] [-v] package extras [extras ...]
Install extra packages into an application.
positional arguments:
package installed application name
extras extra package name[s] to inject/install
options:
-h, --help show this help message and exit
-v, --verbose give more output
Command install
usage: pipxu install [-h] [-p PYTHON | -P PYENV] [-f] [-e] [-d] [-v]
package [package ...]
Install a Python application using an isolated virtual environment.
positional arguments:
package application[s] to install
options:
-h, --help show this help message and exit
-p PYTHON, --python PYTHON
specify explicit python executable path
-P PYENV, --pyenv PYENV
pyenv python version to use, i.e. from `pyenv
versions`, e.g. "3.9".
-f, --force recreate any already installed venv
-e, --editable install application[s] in editable mode
-d, --include-deps include executables from dependencies
-v, --verbose give more output
Command list
usage: pipxu list [-h] [--json] [package ...]
List all applications installed by this tool.
positional arguments:
package list the given application[s] only
options:
-h, --help show this help message and exit
--json output json instead
Command reinstall-all
usage: pipxu reinstall-all [-h] [-p PYTHON | -P PYENV] [-v]
[-s [SKIP ...]]
Reinstall all applications.
options:
-h, --help show this help message and exit
-p PYTHON, --python PYTHON
specify explicit python executable path
-P PYENV, --pyenv PYENV
pyenv python version to use, i.e. from `pyenv
versions`, e.g. "3.9".
-v, --verbose give more output
-s [SKIP ...], --skip [SKIP ...]
skip these applications, e.g. "-s package1 package2"
Command reinstall
usage: pipxu reinstall [-h] [-p PYTHON | -P PYENV] [-v]
package [package ...]
Reinstall an application.
positional arguments:
package application[s] to reinstall
options:
-h, --help show this help message and exit
-p PYTHON, --python PYTHON
specify explicit python executable path
-P PYENV, --pyenv PYENV
pyenv python version to use, i.e. from `pyenv
versions`, e.g. "3.9".
-v, --verbose give more output
Command runpip
usage: pipxu runpip [-h] package [args ...]
Run pip with given arguments on virtual environment for the given application.
positional arguments:
package installed application name
args arguments to pass to uv pip. should start with "--".
options:
-h, --help show this help message and exit
Command uninject
usage: pipxu uninject [-h] [-v] package extras [extras ...]
Uninstall extra packages from an application.
positional arguments:
package installed application name
extras extra package name[s] to uninstall
options:
-h, --help show this help message and exit
-v, --verbose give more output
Command uninstall-all
usage: pipxu uninstall-all [-h] [-v] [-s [SKIP ...]]
Uninstall all applications.
options:
-h, --help show this help message and exit
-v, --verbose give more output
-s [SKIP ...], --skip [SKIP ...]
skip these applications, e.g. "-s package1 package2"
Command uninstall
usage: pipxu uninstall [-h] [-v] package [package ...]
Uninstall an application.
positional arguments:
package application[s] to uninstall
options:
-h, --help show this help message and exit
-v, --verbose give more output
Command upgrade-all
usage: pipxu upgrade-all [-h] [-v] [-s [SKIP ...]]
Upgrade all applications.
options:
-h, --help show this help message and exit
-v, --verbose give more output
-s [SKIP ...], --skip [SKIP ...]
skip these applications, e.g. "-s package1 package2"
Command upgrade
usage: pipxu upgrade [-h] [-v] package [package ...]
Upgrade an application.
positional arguments:
package application[s] to upgrade
options:
-h, --help show this help message and exit
-v, --verbose give more output
Command version
usage: pipxu version [-h] [package]
List installed application versions.
positional arguments:
package report specific application and dependent package versions
options:
-h, --help show this help message and exit
Installation and Upgrade
Python 3.7 or later is required. Arch Linux users can install pipxu
from the AUR and skip this
section.
The uv
program is also required.
The following is an easy way to install it, see
here.
curl -LsSf https://astral.sh/uv/install.sh | sh
Note pipxu
is on PyPI. Run the tiny
bootstrap shell
script
which installs pipxu
to a temporary directory then runs pipxu
from
there to install itself normally.
$ curl -LsSf https://raw.githubusercontent.com/bulletmark/pipxu/main/pipxu-bootstrap | sh
:warning: Note that the pipxu
package also installs the
pipxu-bootstrap
script on your system so you can always recover easily
from a broken pipxu
installation by running that script.
To upgrade:
$ pipxu upgrade pipxu
To uninstall all pipxu
installed applications, and then uninstall
pipxu
itself:
$ pipxu uninstall-all --skip pipxu
$ pipxu uninstall pipxu
Comparison to pipx
Why would you use pipxu
instead of pipx
? The main
reason is to gain a massive speed improvement. pipx
uses python -m venv
to create and install virtual environments and pip
to
install packages whereas pipxu
uses uv
for these operations.
uv
is a new project written in
rust which has a better design than
venv
+ pip
, caches aggressively, and is much
faster. Also, pipx
installs pip
into each virtual environment
using a shared overlay which it has to update periodically so you
sometimes experience pipx
seeming to hang for a while while this
update occurs. pipxu
just creates a minimal lean virtual environment
and uses uv
for all operations so does not need to do this periodic
update.
Note that pipx
offers some esoteric options and features which pipxu
does not have. pipxu
caters for the common use cases. pipxu
never
modifies your PATH.
pipxu
adds some small but handy features not present in pipx
:
-
pipxu
facilitates specifyingpyenv
python versions with an added-P/--pyenv
command option toinstall
. -
You can do
pipxu
commands on an editable projects (as often used by developers) in the current directory by simply typing ".
" as the package name and this works for all commands. E.g.pipxu uninstall .
orpipxu inject . pudb
. I.e.pipxu
automatically determines the package name associated with the current directory. Note thatpipx
accepts ".
" for the install command, but not for any others. -
pipxu
adds adebug
command to run an installed application using a Python debugger. -
If run as root or with
sudo
,pipxu
installs applications to a global location.
Environment Variables
Type pipxu
without any arguments to see usage and the current
environment. The environment is printed at the bottom of the screen
output as follows:
E.g. run as my user "mark":
Environment:
PIPXU_HOME = /home/mark/.local/share/pipxu
PIPXU_BIN_DIR = /home/mark/.local/bin
PIPXU_MAN_DIR = /home/mark/.local/share/man
PIPXU_DEFAULT_PYTHON = python3
Your PATH contains PIPXU_BIN_DIR (/home/mark/.local/bin).
Or run as root, or with sudo
:
Environment:
PIPXU_HOME = /opt/pipxu
PIPXU_BIN_DIR = /usr/local/bin
PIPXU_MAN_DIR = /usr/local/share/man
PIPXU_DEFAULT_PYTHON = python3
WARNING: Your PATH does not contain PIPXU_BIN_DIR (/usr/local/bin).
You can set those environment variables, or provide them as command line
options, to override the defaults if you want. Note, as seen in the
output above, pipxu
reports if PIPXU_BIN_DIR
is included or not in
your PATH. To ensure you can run the applications installed by pipxu
,
that directory must be in your PATH. E.g. for most users on Linux
using the default locations, ensure that ~/.local/bin
is added to
your PATH environment variable.
Command Default Options
You can add default global options to a personal configuration file
~/.config/pipxu-flags.conf
. If that file exists then each line of
options will be concatenated and automatically prepended to your pipxu
command line arguments. Comments in the file (i.e. #
and anything
after on a line) are ignored. Type pipxu
to see all supported options.
The global options: --uv
, --no-man-pages
, --home
, --bin-dir
,
--man-dir
, --default-python
, are the only sensible candidates to
consider setting as defaults.
License
Copyright (C) 2024 Mark Blakeney. This program is distributed under the terms of the GNU General Public License. This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License at http://www.gnu.org/licenses/ for more details.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.