venv_tools

Easier management of python virtual environments using python3 -m venv in bash and zsh.

Synopsis

cd my-repo/
mkvenv      # a virtual environment is created at ./.venv/
            # the new virtual env is automatically activated

pip install -r requirements.txt     # requirements are installed to the virtual environment

cd ../      # the virtual environment is automatically deactivated

cd my-repo/  # the virtual environment is automatically re-activated

Description

Provides automatic virtual environment management with three main functions: mkvenv, rmvenv, and findvenv.

The findvenv function is automatically called on directory changes (via zsh's precmd_functions or bash's PROMPT_COMMAND) to activate/deactivate virtual environments as you navigate your filesystem.

mkvenv

Creates a Python virtual environment in the current working directory at ./.venv/. The virtual environment is stored locally within your project directory, making it easy to manage and delete with the project. The environment is automatically activated upon creation.

Example:

cd ~/projects/myapp
mkvenv
# Virtual environment created at ~/projects/myapp/.venv/
# Environment automatically activated

rmvenv

Safely removes the virtual environment from the current directory. Includes validation checks to ensure you're removing a valid virtual environment directory.

Example:

cd ~/projects/myapp
rmvenv
# Virtual environment at ./.venv/ removed

findvenv

Automatically searches for a .venv/ directory in the current working directory or any parent directory. When found, the virtual environment is activated. When you navigate away from the project, the environment is automatically deactivated.

This function runs automatically on every directory change, so you don't need to manually call it.

Behavior:

• Searches current directory and all parent directories for .venv/
• Activates the first virtual environment found
• Deactivates when you leave the project directory tree
• Properly handles symlinked directories

Installation

For Zsh

Add this line to your ~/.zshrc, ~/.zprofile, or ~/.zlogin:

source /path/to/venv_tools.zsh

For Bash

Add this line to your ~/.bashrc or ~/.bash_profile:

source /path/to/venv_tools.bash

Features

• ✅ Automatic activation/deactivation - Activates venvs when you cd into projects
• ✅ Parent directory search - Finds venvs in parent directories (works in subdirectories)
• ✅ Instant CLI tools - Packages installed via pip are immediately available (no deactivate/reactivate needed)
• ✅ Symlink support - Properly resolves symlinked directories
• ✅ Error handling - Clear error messages with helpful suggestions
• ✅ Shell agnostic - Works in both bash and zsh
• ✅ Local storage - Virtual environments stored in project directories (.venv/)

Development

Running Tests

This project uses ShellCheck for static analysis and BATS for functional testing.

Install test dependencies:

make install-deps
# or manually:
brew install shellcheck bats-core

Run all tests:

make test

Run individual test suites:

make shellcheck  # Static analysis only
make bats        # Functional tests only

Run tests manually:

shellcheck venv_tools_core.sh venv_tools.bash
bats test/

Continuous Integration

Tests run automatically on every push and pull request via GitHub Actions on both Ubuntu and macOS.