vvenv 0.1.0

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 + macOS/Linux) and integrates seamlessly into your shell so that pip install automatically tracks packages.

---

Features

Feature	Description
venvy create venv	Interactively create & configure a venv
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
Shell integration	venvy + / venvy - for activate/deactivate
Existing venv support	Works with any venv, not just venvy-created ones

---

Installation

# Recommended: install globally with pipx
pipx install venvy

# Or with pip (global)
pip install venvy

# Or with pip --user
pip install --user venvy

---

Quick Start

1. Initialize a project

cd my-project
venvy create venv

You'll be asked:

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 .venv/
• Upgrades pip
• Installs ipykernel (if chosen)
• Installs existing requirements (if any)
• Saves config to .venvy/config.json

2. Activate / deactivate

Without shell integration (always works):

# macOS / Linux
source .venv/bin/activate

# Windows (cmd)
.venv\Scripts\activate.bat

# Windows (PowerShell)
.venv\Scripts\Activate.ps1

With shell integration (recommended):

# Set up once:
echo 'eval "$(venvy shell-init)"' >> ~/.bashrc  # or ~/.zshrc
source ~/.bashrc

# Then use anywhere:
venvy +    # activate
venvy -    # deactivate

3. Install packages (auto-tracked)

# With venvy (always works):
venvy pip install requests httpx

# With shell integration, plain pip works too:
pip install requests httpx
# → automatically added to requirements.txt!

pip uninstall requests
# → automatically removed from requirements.txt!

4. Clone a project and restore dependencies

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

---

Shell Integration (Recommended)

Add to your ~/.bashrc or ~/.zshrc:

eval "$(venvy shell-init)"

Restart your terminal. Now:

venvy +              # activates the venv (like npm run)
venvy -              # deactivates the venv

pip install <pkg>    # auto-updates requirements.txt ✓
pip uninstall <pkg>  # auto-removes from requirements.txt ✓

Windows (PowerShell)

Add to your $PROFILE:

venvy shell-init | Invoke-Expression

---

Commands Reference

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

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                Print shell integration script
venvy +                         Activation hint / activate (shell integration)
venvy -                         Deactivation hint / deactivate (shell integration)

venvy --version                 Show version

---

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
}

Add .venvy/ to your .gitignore or commit it — your choice. Commit requirements.txt always.

---

Using an Existing Venv

venvy works with any existing virtual environment — it doesn't need to have created it. As long as:

1. The venv is active ($VIRTUAL_ENV is set), or
2. A .venv, venv, env, or .env directory exists in the project

venvy will find it and manage requirements.txt accordingly.

---

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
pip install -e ".[dev]"
pytest

---

License

MIT