ohmyzsh/plugins/viper-env/README.md

Viper Env Z-Shel plugin

Automatically activates and deactivates python virtualenv upon cd in and out.

Features

• Automatic Activation/Deactivation: Finds and manages virtualenvs in your project directories as you cd.
• Upward Search: Works even if you are in a subdirectory of your project.
• Plays Well With Others: If a viper-env managed environment is active and you cd into a new project, it will correctly deactivate the old one before activating the new one.
• Convenient Manual Activation: When autoloading is disabled, an activate alias is automatically made available in project directories, giving you explicit control.
• State-Aware: Only deactivates environments that it has activated, so it won't interfere when you leave a project that uses another tool.
• Configurable Autoloading: Easily enable or disable the automatic activation/deactivation feature.
• Diagnostic Commands: Supports a quiet mode and provides list, status, and version commands for diagnostics.

Inspiration

Based on blueray's answer, I decided to go one step further and implement it as a Z-Shell plugin.

Usage

Usage

Automatic Mode (Default)

By default, viper-env is configured for a seamless experience. It uses a precmd hook that runs before each prompt, allowing it to activate virtual environments immediately upon creation or when you enter a project directory.

# Create a new project and cd into it
mkdir my-project && cd my-project

# Create a virtual environment
python -m venv .venv
# -> Activating virtual environment .venv

# Go to a subdirectory
mkdir src && cd src
# -> ".venv" stays active

# Leave the project directory
cd ../..
# -> viper-env automatically deactivates ".venv"

Configuration

Using External Virtual Environments (Semi-Automatic Mode)

Tip

For projects where you prefer to keep the virtual environment directory outside of the project folder (e.g., in ~/.virtualenvs/), you can use the semi-automatic mode.

Create a file named .viper-env in your project's root directory and place the absolute path to your virtual environment in it.

# Example: Tell viper-env to use the 'my-project-venv' environment for this project
echo "/home/user/.virtualenvs/my-project-venv" > .viper-env

viper-env will prioritize this file over automatically discovered venvs.

Disabling and Enabling Autoloading

If you wish to temporarily disable the automatic activation and deactivation behavior, you can use the autoload --disable command. This acts as a master switch.

viper-env autoload --disable

With autoloading disabled, viper-env will not perform any actions as you change directories. You can re-enable the automatic behavior at any time:

viper-env autoload --enable

Instalation

Oh my Zsh

Git clone this repository to the Oh my Zsh custom plugins folder.

Add plugin to plugins directive in ~/.zshrc

plugins=(
  # put local oh-my-zsh plugins here
  viper-env
)

source $HOME/.oh-my-zsh/oh-my-zsh.sh

Antigen

It is recommended to use a .antigenrc file. Then add the following to it:

antigen bundle DanielAtKrypton/viper-env

# Apply changes
antigen apply

Make sure in your .zshrc Antigen is loading the .antigenrc file as follows:

antigen init ~/.antigenrc