venv-manager

venv-manager

A Python virtual-environment runtime for humans and AI agents.

Written in Go. One static binary, no runtime deps beyond python3 (or uv, if available).

The GIF above is real: venv-manager watch app.py --venv X monitors a file, scans its imports with a tiny AST-lite parser, and pip-installs whatever is missing — every time the file changes. Point it at a script an LLM is iterating on and the venv converges as the code does.

Why

Two failure modes drove this tool:

1. Human sprawl. Venvs multiply across ~, cache directories eat GB, activation syntax varies by shell, and cloning "the env that worked" means copy-pasting pip freeze between terminals.
2. Agent sprawl. LLMs generating Python routinely pip install into the wrong interpreter, forget to set VIRTUAL_ENV, leave half-installed packages behind after a crash, and have no typed API to reason about environment state — only shells.

venv-manager solves (1) with a clean CLI and (2) with a Model Context Protocol server, typed JSON snapshots, ephemeral venvs with OS-level sandboxing, and a file watcher that keeps a venv in sync with an evolving script.

Install

curl -sSL https://raw.githubusercontent.com/jacopobonomi/venv_manager/main/install.sh | bash

Or from source:

git clone https://github.com/jacopobonomi/venv_manager && cd venv_manager
make install

Requires Go 1.21+ to build, Python 3.x at runtime.

AI integration

MCP server

Exposes venv operations as native Model Context Protocol tools. Agentic clients (Claude Desktop, Cursor, Zed) call typed tools with JSON Schemas instead of guessing shell invocations.

Wire it up in Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "venv-manager": {
      "command": "venv-manager",
      "args": ["mcp"]
    }
  }
}

Tools exposed (JSON-RPC 2.0 over stdio):

Implementation: ~350 LOC, zero third-party MCP deps. Newline-delimited JSON-RPC 2.0 on stdin/stdout.

Ephemeral execution (uvx-style, sandboxed)

# create → install → run → destroy, all in one call
venv-manager exec --with requests -- python -c "import requests; print(requests.__version__)"

# with an OS sandbox: no network, no writes outside /tmp + the ephemeral venv
venv-manager exec --sandbox --with pandas -- python untrusted.py

--sandbox uses sandbox-exec on macOS and bwrap on Linux. Deny-by-default profile with explicit allow-lists for the venv path, /tmp, and process management. Network is unshared.

File watcher

venv-manager watch app.py --venv myenv

fsnotify on the parent directory (survives editor atomic-rename writes), 500 ms debounce, then:

1. AST-lite regex scan of .py files (skips docstrings, relative imports, and vendored dirs like .venv, .git, __pycache__, node_modules)
2. Filter against a stdlib module set
3. Resolve import-name → pip-package aliases (cv2 → opencv-python, sklearn → scikit-learn, PIL → Pillow, bs4 → beautifulsoup4, yaml → PyYAML, ...)
4. Diff against installed packages
5. pip install the delta

The venv is always a superset of the current file's requirements. This is the loop the demo GIF above exercises.

JSON snapshot as a single-call context primer

venv-manager describe myenv

{
  "name": "myenv",
  "path": "/Users/me/.venvs/myenv",
  "python_version": "3.12.6",
  "python_path": "/Users/me/.venvs/myenv/bin/python",
  "pip_path": "/Users/me/.venvs/myenv/bin/pip",
  "packages": ["requests==2.34.2", "rich==15.0.0", ...],
  "package_count": 12,
  "size_bytes": 45123456,
  "size_human": "43.03 MB",
  "modified_at": "2026-07-20T15:41:35Z",
  "freeze_hash": "sha256:2c58d830...",
  "activation": {
    "bash": "source /Users/me/.venvs/myenv/bin/activate",
    "zsh":  "source /Users/me/.venvs/myenv/bin/activate",
    "fish": "source /Users/me/.venvs/myenv/bin/activate.fish",
    "pwsh": "/Users/me/.venvs/myenv/bin\\Activate.ps1",
    "cmd":  "/Users/me/.venvs/myenv/bin\\activate.bat"
  }
}

One tool call, everything an agent needs to reason about the environment. freeze_hash lets an agent detect drift between two describe calls in O(1) instead of diffing package lists.

Commands

Most read commands also accept --json for stable, machine-parseable output.

Configuration

~/.config/venv-manager/config.json (respects $XDG_CONFIG_HOME and $VENV_MANAGER_CONFIG):

{
  "base_dir": "/custom/path/to/venvs",
  "default_python": "3.12",
  "use_uv": true,
  "prune_after_days": 90
}

Bootstrap: venv-manager config init.

uv backend

If uv is on PATH and use_uv: true, create runs uv venv. Typically 10–100× faster than python -m venv on cold cache.

Development

make build            # go build -o bin/venv-manager
make test             # unit tests
make demo             # regenerate scripts/demo/demo.gif via VHS
go test -tags=integration ./internal/manager/...   # integration tests (real pip, real PyPI)

CI runs go vet, go test -race on Ubuntu + macOS, and integration tests on Ubuntu with Python 3.12.

Architecture:

cmd/venv-manager/           cobra CLI
internal/manager/           core operations (create, install, snapshot, scan, watch, exec, describe, ...)
internal/config/            XDG-aware JSON config
internal/mcp/               JSON-RPC 2.0 MCP server (stdio)
internal/tui/               Bubble Tea browser
internal/utils/             platform helpers, size formatting

License

MIT.

Author

Jacopo Bonomi