uvenv: pipx for uv

pypi wheels snapcraft

Inspired by:

pipx
uv

Installation

New: uvenv is now also installable via the snap store.
The pip method is still recommended, but if you want to use snap, please check out docs/snap.md!

Install via pip (or alternatives):

pip install uvenv  
# or `uv install uvenv`, `pipx install uvenv`

Note: On some systems (e.g., Ubuntu 24.04+), global installation via pip is restricted by default. The recommended way to install uvenv for these systems is to use the install.sh script:
$SHELL -c "$(curl -fsSL https://raw.githubusercontent.com/robinvandernoord/uvenv/uvenv/install.sh)"
# instead of `$SHELL`, you can also use `sh`, `bash`, `zsh`
> ```
For more installation alternatives, see [docs/installation.md](docs/installation.md) if you encounter `externally-managed-environment` errors.

Optional (for bash users):
```
uvenv setup
```
This installs the following features:

Ensures ~/.local/bin/ is added to your PATH, so commands can be found (unless --skip-ensurepath). Can also be activated via uvenv ensurepath
Enables tab completion for uvenv (unless --skip-completions). Can also be enabled via uvenv completions --install.
Enables uvenv activate (unless --skip-activate) to activate uvenv-managed virtualenvs from your shell

Usage

uvenv

Most pipx commands are supported, such as install, upgrade inject, run, runpip.
Run uvenv without any arguments to see all possible subcommands.

🆕 Freeze and Thaw

You can snapshot your current setup into a uvenv.lock file using:

uvenv freeze

This lock file records all installed applications along with their metadata — including version, Python version, and any injected dependencies.

Later, you can restore that exact setup using:

uvenv thaw

This is useful for replicating the same setup on a different machine, or after a clean install or system update.

Lock file formats

The uvenv.lock file can be saved in one of the following formats:

TOML (default): human-readable and easy to edit
JSON: more verbose, but script-friendly (e.g. with jq)
Binary: compact, but not human-readable

Choose the format using the --format flag:

uvenv freeze --format json

See docs/lockfile_v1.md for details on the file format, including all supported options and examples.

Selective freeze/thaw

Use --include or --exclude to control which apps get recorded or restored:

uvenv freeze --exclude some-app
uvenv thaw --include only-this-app

For all available options, see:

uvenv freeze --help
uvenv thaw --help

Migrating from `uvx` and Comparing with `uv tool`

Migrating from `uvx`

The tool previously named uvx is now uvenv due to a naming collision with a new uv command. The new name better reflects its purpose, combining uv with venv. You can run uvenv self migrate to move your environments and installed commands from uvx to uvenv.

How `uvenv` differs from `uv tool`

While both uvenv and uv tool (a subcommand of uv) offer overlapping functionality for installing and running Python applications, they differ in purpose and approach:

Interface: uvenv is modeled after pipx, offering commands like install, inject, run, upgrade, and runpip. If you're already used to pipx, uvenv is a near drop-in replacement.
Inject support: uvenv supports pipx's inject functionality, which lets you add extra packages to an app’s environment — helpful for plugins, linters, or testing tools. uv tool does not currently support this.
Compatibility: uvenv uses uv for dependency resolution and installation, benefiting from its speed and correctness. It also respects uv's configuration files (such as ~/.config/uv/uv.toml and /etc/uv/uv.toml, see uv config docs) unless the environment variable UV_NO_CONFIG=1 is set to ignore them.

In short:

Use uvenv if you want pipx-style workflows with advanced management features.
Use uv tool if you prefer a minimal approach for running tools quickly - for most basic use-cases, uv tool is probably sufficient.

Platform Considerations

Rust-Powered Performance (uvenv 2.0): Starting from version 2.0, uvenv leverages Rust for improved performance and compatibility with uv.
Prebuilt Binaries: Currently, prebuilt binaries are available for x86_64 (amd64) and aarch64 (ARM64) on Linux, as well as Intel (x86_64) and Apple Silicon (ARM64) on macOS.
Other Platforms: If you're on a different platform, you can still use uvx 1.x, which is written in pure Python. Find it at robinvandernoord/uvx.

Alternatively, you can Compile for Your Platform:

Install the Rust toolchain:
```
curl https://sh.rustup.rs -sSf | sh
```

Clone the uvenv repo and navigate to it:

git clone https://github.com/robinvandernoord/uvenv.git
cd uvenv

Set up a virtual environment (choose Python or uv):

python -m venv venv  # or `uv venv venv --seed`
source venv/bin/activate

Install Maturin (Python with Rust package builder):

pip install maturin  # or `uv pip install maturin`

Compile and install the uvenv binary:
```
maturin develop
```
Now you can use uvenv:
```
./venv/bin/uvenv
```

For additional details on building and distribution, refer to maturin documentation.

License

uvenv is distributed under the terms of the MIT license.

Changelog

See CHANGELOG.md on GitHub

Release files for uvenv 3.11.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for uvenv 3.11.1
File	Size	Uploaded
uvenv-3.11.1.tar.gz	110.0 kB	Sep 10, 2026	Details

Built distributions (wheels)

Table of built distributions (wheels) for uvenv 3.11.1
File	Interpreter	ABI	Platform	Reset
uvenv-3.11.1-py3-none-musllinux_1_2_x86_64.whl 7.7 MB Sep 10, 2026	Python 3	none	Linux musl 1.2+ x86-64	Details
uvenv-3.11.1-py3-none-musllinux_1_2_aarch64.whl 7.3 MB Sep 10, 2026	Python 3	none	Linux musl 1.2+ ARM64	Details
uvenv-3.11.1-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl 7.7 MB Sep 10, 2026	Python 3	none	Linux glibc 2.17+ x86-64	Details
uvenv-3.11.1-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl 7.3 MB Sep 10, 2026	Python 3	none	Linux glibc 2.17+ ARM64	Details
uvenv-3.11.1-py3-none-macosx_11_0_arm64.whl 6.1 MB Sep 10, 2026	Python 3	none	macOS 11.0+ ARM64	Details

Total release size: 36.3 MB

Release files / uvenv-3.11.1.tar.gz

Download URL	uvenv-3.11.1.tar.gz
Size	110.0 kB
Tags	Source
SHA-256 checksum How to use checksums	`ef75955bf5e7c41d9a00ecfe81884dd1f7487d2cd1bee5144dda1c29f6342ec5`
BLAKE2b-256 checksum How to use checksums	`271b3159fe7bb6981c1ec965ad1d616c31232f5c9732295a34074a3414145559`
Upload date	Sep 10, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`maturin/1.15.0`

Release files / uvenv-3.11.1-py3-none-musllinux_1_2_x86_64.whl

Download URL	uvenv-3.11.1-py3-none-musllinux_1_2_x86_64.whl
Size	7.7 MB
Tags	Linux musl 1.2+ x86-64 Python 3
SHA-256 checksum How to use checksums	`9050b6bd212d251f34a688ceefa2ae02127481730fc982b0cfd96503f1fbed41`
BLAKE2b-256 checksum How to use checksums	`2c7b5e2150784963878904f3d1c7516f8aee0dda43834d7ad3d3bae767d2f54e`
Upload date	Sep 10, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`maturin/1.15.0`

Release files / uvenv-3.11.1-py3-none-musllinux_1_2_aarch64.whl

Download URL	uvenv-3.11.1-py3-none-musllinux_1_2_aarch64.whl
Size	7.3 MB
Tags	Linux musl 1.2+ ARM64 Python 3
SHA-256 checksum How to use checksums	`30dd19d9003e0a2e383e3c3555ff3be211f9969331cb4d46dbc19342379f76f2`
BLAKE2b-256 checksum How to use checksums	`d29efabe68177ec055829ba8c0f5c912192e08ddcc87d294ed7abee069fb47b2`
Upload date	Sep 10, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`maturin/1.15.0`

Release files / uvenv-3.11.1-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

Download URL	uvenv-3.11.1-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Size	7.7 MB
Tags	Linux glibc 2.17+ x86-64 Python 3
SHA-256 checksum How to use checksums	`7926b0af0081ca6ebe57ce05443e78760530c0f303b75d3685abd50ec3aeadd9`
BLAKE2b-256 checksum How to use checksums	`d2c4e180c8a6ca6db3890331bad152e85bc7f8eb8e4b1c4f7cabdc472f47d5e3`
Upload date	Sep 10, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`maturin/1.15.0`

Release files / uvenv-3.11.1-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl

Download URL	uvenv-3.11.1-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Size	7.3 MB
Tags	Linux glibc 2.17+ ARM64 Python 3
SHA-256 checksum How to use checksums	`a5dfef52d55ff09ebd5a1c6428bd77934329cae3ac913bf0970d79d3d5a73a75`
BLAKE2b-256 checksum How to use checksums	`e1da6e65c2129e9e53d3a79873e2d06d53fd7efd6e770688e46b994f0ba6494f`
Upload date	Sep 10, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`maturin/1.15.0`

Release files / uvenv-3.11.1-py3-none-macosx_11_0_arm64.whl

Download URL	uvenv-3.11.1-py3-none-macosx_11_0_arm64.whl
Size	6.1 MB
Tags	Python 3 macOS 11.0+ ARM64
SHA-256 checksum How to use checksums	`ec71beefd1fb05a9e197d1f9eff62f63ad0b840e0543b8b534d5ab17022afac4`
BLAKE2b-256 checksum How to use checksums	`3f009d1a4ba6d76e505c56b3711a78624b5481932661fad6351da2d4b9ad9c23`
Upload date	Sep 10, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`maturin/1.15.0`