vvenv 0.1.1

Smart Python virtual environment manager — like package.json but for Python

venvy 🐍

Smart Python virtual environment manager — like package.json for Python.

venvy takes the pain out of managing Python virtual environments and requirements.txt. It works cross-platform (Windows CMD/PowerShell + macOS/Linux bash/zsh) with zero shell setup required.

---

Features

Feature	Description
venvy create venv	Interactively create & configure a venv
venvy +	Activate venv — no setup needed, works everywhere
venvy -	Deactivate / exit venv shell
venvy pip install <pkg>	Install + auto-add to requirements
venvy pip uninstall <pkg>	Uninstall + auto-remove from requirements
venvy status	Show venv & requirements info
venvy sync	Install all packages from requirements
venvy list	List tracked packages

---

Installation

# Recommended: install globally with pipx
pipx install venvy

# Or with pip (global)
pip install venvy

---

Quick Start

1. Create a virtual environment

cd my-project
venvy create venv

You'll be asked two questions:

venvy — virtual environment setup
────────────────────────────────────────
  [1/2] Install ipykernel (for Jupyter notebook support)? [y/N]: n
  [2/2] Requirements file name [requirements.txt]:

venvy then creates the venv, upgrades pip, installs any existing requirements, and saves config.

---

2. Activate / deactivate — zero setup, works everywhere

venvy +

That's it. venvy spawns a new interactive shell with the venv already activated. Your prompt changes automatically:

# Windows CMD:
(.venv) D:\my-project>

# macOS/Linux bash:
(.venv) user@machine:~/my-project$

To deactivate — just exit the shell:

exit
# or:
venvy -

How it works: venvy + spawns a new shell process with the venv's Scripts/ (Windows) or bin/ (macOS/Linux) prepended to PATH and VIRTUAL_ENV set — exactly what source activate does, but without needing to modify the parent shell's environment. No eval, no source, no configuration.

---

3. Install packages (auto-tracked in requirements.txt)

venvy pip install requests httpx
# → installs packages AND adds them to requirements.txt automatically

venvy pip uninstall requests
# → uninstalls AND removes from requirements.txt

Or use plain pip when the venv is active (via venvy +) — then use venvy pip for requirement tracking.

---

4. Clone a project and restore dependencies

git clone https://github.com/user/project
cd project
venvy create venv    # reads existing requirements.txt and installs everything
# or if venv already exists:
venvy sync

---

All Commands

venvy create venv [options]     Create virtual environment
  --name  -n    Venv directory name (default: .venv)
  --requirements -r   Requirements file name (prompted if not given)
  --ipykernel         Pre-select ipykernel installation
  --yes -y            Skip all prompts, use defaults

venvy +                         Activate venv (spawns shell, no setup needed)
venvy -                         Deactivate venv / exit

venvy pip install <packages>    Install & track packages
  --upgrade -U  Upgrade packages
venvy pip uninstall <packages>  Uninstall & untrack packages
  --yes -y      Skip confirmation

venvy status                    Show environment info
venvy list                      List tracked packages
venvy sync                      Install all requirements

venvy shell-init                (Optional) print shell integration for native pip tracking

venvy --version                 Show version

---

Works With Existing Venvs

venvy works with any existing virtual environment — it doesn't need to have created it. If a .venv, venv, env, or .env directory exists, venvy finds it and manages requirements.txt accordingly.

python -m venv .venv            # created manually
venvy +                         # venvy finds and activates it ✓
venvy pip install flask         # tracked in requirements.txt ✓

---

Project Structure

After venvy create venv:

my-project/
├── .venv/                  ← virtual environment
├── .venvy/
│   └── config.json         ← venvy project config
├── requirements.txt        ← auto-managed
└── your code...

.venvy/config.json example:

{
  "venv_name": ".venv",
  "requirements_file": "requirements.txt",
  "install_ipykernel": false
}

---

Optional: Native pip auto-tracking

For plain pip install to auto-update requirements.txt without using venvy pip, add the optional shell integration:

macOS/Linux — add to ~/.bashrc or ~/.zshrc:

eval "$(venvy shell-init)"

Windows PowerShell — add to $PROFILE:

venvy shell-init | Invoke-Expression

This is entirely optional — venvy pip install always works without it.

---

Philosophy

venvy brings package.json-style dependency management to Python:

npm / Node	venvy / Python
npm init	venvy create venv
npm install <pkg>	venvy pip install <pkg>
npm uninstall <pkg>	venvy pip uninstall <pkg>
npm install (restore)	venvy sync
package.json	requirements.txt
node_modules/	.venv/

---

Development

git clone https://github.com/yourorg/venvy
cd venvy
python -m venv .venv
source .venv/bin/activate   # or: venvy +
pip install -e ".[dev]"
pytest

---

License

MIT