uvn

uvn is a centralized Python virtual environment manager designed to work alongside uv, similar to conda for general environment management.

Highlights

• 🎯 Centralized Environments: Manage all environments from a single location.
• 🛠️ uv Integration: Complements uv to streamline virtual environment management.
• ⚡️ Simple CLI Interface: Easily list, create, activate, and remove environments with straightforward commands.
• 🗂️ Export Options: Quickly export configurations as requirements.txt or inline script metadata.
• 💾 Cloning: Easily clone environments to create new ones.
• 🚀 Minimal Dependencies: Designed for simplicity and speed.

Installation

Install uv first.

# On macOS and Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# On Windows
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Then, install uvn with the cli extra.

# From PyPI
uv tool install uvn[cli]

# From GitHub
uv tool install uvn[cli] @ git+https://github.com/xmodar/uvn

Finally, install uvna for easy shell activation (e.g., in ~/.bashrc for bash).

target="~/.bashrc"
uvna=$(cat <<'EOF'
uvna() {
    activate=$(uvn activate --quiet "$1")
    if [[ -n "$activate" ]]; then
        eval "$activate"
    else
        uvn list
        echo "Could not activate '"$1"'!" >&2
    fi
}
EOF
)
target="${target/#\~/$HOME}"
if [[ -f "$target" ]] && grep -q "uvna() {" "$target"; then
  sed -i "/^uvna() {/,/^}$/d" "$target"
fi
echo "$uvna" >> "$target"
source "$target"

Usage

After installing uvn, manage virtual environments that are centralized and accessible from any directory, similar to conda.

Quick Start

To begin, create and activate an environment.

uvn create test --python 3.12
uvna test

The list and remove commands are simple.

# List environments with their sizes
uvn list --size

# Remove the 'test' environment
uvn remove test

To install packages, you can simply use uv pip in an activated environment.

uvna test
uv pip install # ...

The export command offers various options for exporting environment configurations.

# Print dependencies as in requirements.txt
uvn export test

# Export inline script metadata
uvn export test py --short --lower

# Generate a requirements.txt file
uvn export test requirements.txt

# Prepend inline script metadata (automatically detects ".py")
uvn export test script.py

# Clone the environment
uvn fork test test2

Commands

Available commands in uvn:

Usage: uvn [OPTIONS] COMMAND [ARGS]...

╭─ Commands ──────────────────────────────────────────────────────────────────────────────────────────╮
  list       List all virtual environments.
  create     Create a virtual environment.
  remove     Remove a virtual environment.
  export     Export a virtual environment.
  fork       Copy a virtual environment.
  activate   Show environment command.
  version    Show uvn version.
╰─────────────────────────────────────────────────────────────────────────────────────────────────────╯

╭─ Options ───────────────────────────────────────────────────────────────────────────────────────────╮
 --install-completion Install completion for the current shell.
 --show-completion    Show completion for the current shell, to copy it or customize the installation.
 --help               Show this message and exit.
╰─────────────────────────────────────────────────────────────────────────────────────────────────────╯

Contributing

Contributions are welcome! For suggestions or issues, please submit a pull request or open an issue on GitHub.