This guide shows the commands to install uvenv. You run them in your own terminal.
uvenv installs Python command-line apps the way pipx does: each app gets its own virtual environment, and uv resolves and installs the packages. uvenv itself is a single binary written in Rust.
pip install uvenv
uvenv is distributed under the MIT license. Accept it to continue.
MIT License
Copyright (c) Robin van der Noord
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Untick anything you would rather set up yourself.
The snap cannot edit your shell configuration, so uvenv setup is left out. Add ~/snap/uvenv/current/.local/bin to your PATH yourself.
Install method
pip
Shell features
PATH, tab completion, uvenv activate
Click Show example to see what your terminal prints when you run these.
Running the example.
Once the commands have run, install your first app by its name on PyPI:
uvenv install httpie
Close guide
Close this guide? You can start it again at any time.
uvenv Help
Click a book to open it, then click a topic.
Type a word, such as lockfile or python.
What uvenv is
uvenv installs Python command-line apps, such as black, httpie or pgcli, in separate virtual environments with their own dependencies, isolated from your system Python. Their commands are linked into ~/.local/bin, so you run them like any other program.
uvenv has the commands you know from pipx, including install, inject, run and upgrade. It uses uv to resolve and install packages, and uvenv itself is a single binary written in Rust.
uvenv reads uv's configuration files (~/.config/uv/uv.toml and /etc/uv/uv.toml) for settings such as package indexes. Set UV_NO_CONFIG=1 to ignore them.
If you use uv or pipx, you can install uvenv in a virtual environment that they manage:
uv tool install uvenv
pipx install uvenv
If pip reports externally-managed-environment
Some systems, such as Ubuntu 24.04 and later, block global pip installs. Use the install script instead. It downloads uv, installs the latest uvenv into ~/.local/uvenv/venvs/uvenv and links it into ~/.local/bin. You can read the script before you run it.
It makes three changes to your ~/.bashrc or ~/.zshrc. You can skip any of them:
Adds ~/.local/bin to your PATH
So the commands of installed apps can be found. Skip with --skip-ensurepath, or do it on its own with uvenv ensurepath.
Tab completion
For every uvenv command. Skip with --skip-completions, or add it later with uvenv completions --install.
uvenv activate
Lets you activate an app's virtual environment in your current shell. Skip with --skip-activate.
Restart your shell afterwards, for example with exec bash, so the changes take effect. Run setup again with --force to redo it without checking what is already there.
uvenv created a virtual environment for pgcli in ~/.local/uvenv/venvs/pgcli and linked its pgcli command into ~/.local/bin. You can now run pgcli from anywhere.
See what you have installed, and whether updates are available:
$ uvenv list
Use --short for one line per app, or --json for scripts.
Version numbers in these examples are only examples.
If another tool already put a command with the same name in ~/.local/bin, --force overwrites it.
Remove an app and its commands:
$ uvenv uninstall pgcli🗑️ pgcli (4.3.0) removed!
If an app breaks, reinstall it from the package specification you first installed it with. Injected packages are reinstalled too, unless you pass --without-injected.
Some apps need additional packages in their virtual environment, such as a database driver or a plugin. inject installs them into that one app's environment.
$ uvenv inject pgcli psycopg-binary💉 Injected [psycopg-binary] into pgcli.
Remove injected packages with uninject, or its alias eject:
$ uvenv eject pgcli psycopg-binary
uvenv records what you inject. Upgrades and reinstalls keep those packages unless you pass --skip-injected or --without-injected, and freeze writes them to the lockfile.
$ uvenv upgrade pgcli🚀 Successfully updated 'pgcli' from version 4.2.0 to version 4.3.0!$ uvenv upgrade-all
Upgrades stay within the version constraint you installed with, for example "pgcli<5". Use --force to ignore it. Injected packages are upgraded too, unless you pass --skip-injected.
To see what is out of date, and whether any app's commands are missing or broken:
$ uvenv check✅ No issues found. Everything is up-to-date and all scripts are properly installed!
Install uvenv on the new machine, then run thaw in the directory that holds your lockfile:
$ uvenv thaw
It looks for uvenv.lock, uvenv.toml or uvenv.json, or the file you name with --filename, and installs every app in it.
--skip-current leaves apps you already have alone. --remove-current deletes all uvenv-managed virtual environments before installing the apps from the lockfile.
By default each app gets the Python version it was frozen with. --python ignore uses your default Python instead, and --python 3.12 uses that version for everything.
The package and any constraint, as you would pass it to install. Required.
version
The version to install.
python
The Python version the app was frozen with. Can be empty.
injected
Packages that were injected into the app.
editable
Whether the app is installed in editable mode.
freeze --format json and --format binary store the same fields as JSON or as a compact binary file. You can also write the TOML by hand. Only spec is required, and each app can also be written as its own table, [packages.pgcli], with one field per line.