Higangssh/pvm: A fast CLI to discover, alias, and run Python virtual environments — with an interactive TUI · GitHub

A fast CLI to discover, alias, and run Python virtual environments — with an interactive TUI.

Windows and macOS supported. Linux support planned.

• 🔍 Auto-discovery — scan any directory and register all venvs found
• 🏷️ Aliases — give each venv a short memorable name
• ⚡ Run anywhere — execute Python or any command inside a venv from a single CLI
• 🔖 Saved commands — bookmark frequently used commands per venv
• 🖥️ Interactive TUI — browse and pick venvs with arrow keys (pvm ui)
• 📦 Single binary — ~6 MB, no dependencies to install

Pick whichever you prefer:

Windows:

irm https://raw.githubusercontent.com/Higangssh/pvm/main/install.ps1 | iex

macOS:

curl -fsSL https://raw.githubusercontent.com/Higangssh/pvm/main/install.sh | sh

Downloads the latest binary and adds it to your user PATH. Restart your terminal, or source your shell rc, then run pvm --help.

1. Download the right binary from the latest release.
   • Windows: pvm.exe
   • macOS Intel: pvm-darwin-amd64
   • macOS Apple Silicon: pvm-darwin-arm64
2. Rename it to pvm on macOS if needed, then place it somewhere on your PATH.
3. Run it:

   ./pvm --help

git clone https://github.com/Higangssh/pvm.git
cd pvm
go build -o pvm.exe .

macOS:

git clone https://github.com/Higangssh/pvm.git
cd pvm
go build -o pvm .

# 1. Discover every venv under a workspace
pvm scan C:\projects

# 2. See what got registered
pvm list

# 3. Run something
pvm shell my-app                  # open an activated shell
pvm exec my-app -- pip list       # run any command in the venv
pvm run  my-app script.py         # run python with args

pvm does not auto-scan on list.

That means your first run is usually:

pvm scan C:\projects
pvm list

• scan = find venvs and register them
• list = show already-registered venvs
• add = register one venv manually
• remove = remove one registered venv by alias

When you run scan, pvm creates aliases for you automatically.

• If the folder name is .venv, venv, or env, it uses the parent folder name
  • C:\work\my-api\.venv → my-api
• Otherwise it uses the venv folder name itself
  • C:\work\my-api\backend-runtime → backend-runtime

If the alias already exists, pvm adds a number like 2, 3, etc.

Both commands now show exactly what they are about to change and ask for confirmation.

pvm add C:\work\my-api\.venv
# Add my-api (C:\work\my-api\.venv)? [y/N]

pvm remove my-api
# Remove my-api (C:\work\my-api\.venv)? [y/N]

Use -y or --yes to skip confirmation.

Run pvm ui for a full-screen browser (shown in the demo above).

Keybindings: enter/s = shell · r = run · x = exec · d = remove · / = filter · q = quit

# Register all venvs under a workspace folder
pvm scan C:\projects
# + my-api    C:\projects\my-api\venv
# + my-app    C:\projects\my-app\.venv
# Added 2 venv(s).

# See aliases before removing anything
pvm list

# Add one env manually
pvm add C:\projects\tools\backend-runtime

# Remove one env safely
pvm remove my-api

# Skip confirmation when you want automation
pvm add C:\projects\tools\backend-runtime -y
pvm remove my-api -y

# Quick Python check
pvm run my-api --version
# Python 3.12.0

# Install a package inside the venv
pvm exec my-api -- pip install requests

# Bookmark a common command
pvm save my-api serve python manage.py runserver 0.0.0.0:8000
pvm save my-api test  pytest -v

# Use the bookmark
pvm do my-api serve
pvm do my-api test

# Interactive mode
pvm ui

• run — runs the venv's python.exe. Good for scripts and python -m ....
• exec — runs any command with venv PATH/VIRTUAL_ENV injected. Use for pip, pytest, django-admin, etc.
• shell — opens an interactive shell with the venv activated. On Windows this uses cmd. On macOS it starts your current login shell in the current terminal session.

Stored at the standard user config directory:

• Windows: %APPDATA%\\pvm\\config.json
• macOS: ~/Library/Application Support/pvm/config.json

It's plain JSON, feel free to edit by hand or back it up.

{
  "venvs": [
    {
      "alias": "my-api",
      "path": "C:\\projects\\my-api\\venv",
      "commands": {
        "serve": "python manage.py runserver 0.0.0.0:8000",
        "test":  "pytest -v"
      }
    }
  ]
}

Windows:

irm https://raw.githubusercontent.com/Higangssh/pvm/main/uninstall.ps1 | iex

macOS:

curl -fsSL https://raw.githubusercontent.com/Higangssh/pvm/main/uninstall.sh | sh

Removes the installed binary and optionally deletes the config file.

# 1. Remove the binary folder
Remove-Item -Recurse -Force "$env:LOCALAPPDATA\pvm"

# 2. (Optional) Remove your saved venv list
Remove-Item -Recurse -Force "$env:APPDATA\pvm"

# 3. Remove from PATH
#    Win + R -> sysdm.cpl -> Advanced -> Environment Variables
#    Edit user `Path` -> remove the `...\AppData\Local\pvm` entry

No services, registry entries, or background processes are ever created — pvm is just an executable file.

• Linux support
• pvm create <path> — create new venvs
• pvm pip-freeze / pvm pip-sync across venvs
• Per-project .pvm file to auto-select venv
• Packaged releases (scoop, winget, brew)

MIT