virtualenvwrapper

6.1.1 · active · verified Thu Apr 16

virtualenvwrapper is a set of extensions for Ian Bicking's virtualenv tool, designed to simplify the management of Python virtual environments. It organizes all environments in one place, provides wrappers for creating, copying, and deleting environments, and enables quick switching between them with tab completion. The current version is 6.1.1, and it is actively maintained with a focus on modern Python versions.

Common errors

```
virtualenvwrapper.sh: There was a problem running the initialization hooks. If Python could not import the module virtualenvwrapper.hook_loader, check that virtualenvwrapper has been installed for VIRTUALENVWRAPPER_PYTHON=/usr/bin/python3 and that PATH is set properly.
```
cause The Python interpreter specified by `VIRTUALENVWRAPPER_PYTHON` cannot find the `virtualenvwrapper` module, often because it was installed for a different Python version or in a location not in `PATH`.

fix Ensure `virtualenvwrapper` is installed for the Python version pointed to by `VIRTUALENVWRAPPER_PYTHON`. Update your shell startup file to set `VIRTUALENVWRAPPER_PYTHON` to the *exact* path of the Python interpreter where `virtualenvwrapper` is installed (e.g., `export VIRTUALENVWRAPPER_PYTHON=/usr/bin/python3`). Ensure this `export` line comes *before* the `source virtualenvwrapper.sh` line.
```
-bash: /usr/local/bin/virtualenvwrapper.sh: No such file or directory
```
cause The `virtualenvwrapper.sh` script was not found at the specified path, often due to variations in pip's installation location or using `--user` installs.

fix First, locate the actual `virtualenvwrapper.sh` script (e.g., using `find / -name virtualenvwrapper.sh 2>/dev/null` or `which virtualenvwrapper.sh` after install). Then, update the `source` command in your shell startup file to reflect the correct path (e.g., `source $(python3 -m site --user-base)/bin/virtualenvwrapper.sh` or `source ~/.local/bin/virtualenvwrapper.sh`).
```
mkvirtualenv: command not found
```
cause The `virtualenvwrapper.sh` script, which defines these commands, has not been properly sourced into your current shell session.

fix Ensure `virtualenvwrapper.sh` is sourced in your shell startup file (`~/.bashrc`, `~/.zshrc`, etc.) and that you have reloaded your shell (either by `source ~/.bashrc` or opening a new terminal window).
```
ERROR: Project directory '/path/to/project' does not exist. Create it or set PROJECT_HOME to an existing directory.
```
cause When using `mkproject`, the directory specified by `PROJECT_HOME` or the target project directory does not exist.

fix Before running `mkproject`, ensure the directory specified by your `PROJECT_HOME` environment variable exists, or create the target project directory manually. For example: `mkdir -p $HOME/Projects` then `export PROJECT_HOME=$HOME/Projects`.

Warnings

breaking Python 2 support was formally dropped in virtualenvwrapper 6.x. Attempts to use it with Python 2 will fail or lead to unexpected behavior.
Fix: Ensure you are using Python 3.8+ and that VIRTUALENVWRAPPER_PYTHON points to a Python 3 interpreter.
breaking The `toggleglobalsitepackages` command was removed in virtualenvwrapper 6.x because the underlying capability was removed from virtualenv itself.
Fix: This feature is no longer supported. Manage site-packages inclusion when creating the virtual environment using virtualenv's options directly.
breaking Support for `ksh` shell was dropped in virtualenvwrapper 6.x.
Fix: Use a supported shell like `bash` or `zsh`.
gotcha For Python 3.12+, global pip installs are discouraged due to stricter rules to prevent system package conflicts. Installing virtualenvwrapper globally with `pip install virtualenvwrapper` might not make it accessible to your shell or lead to `ModuleNotFoundError` for `virtualenvwrapper.hook_loader`.
Fix: Consider installing virtualenvwrapper within its own dedicated virtual environment using `python3 -m venv` and then configuring your shell to source `virtualenvwrapper.sh` from *that* venv's `bin` directory.
gotcha Windows users should install `virtualenvwrapper-win` instead of `virtualenvwrapper`. The core `virtualenvwrapper` is a set of shell scripts designed for Unix-like environments (Linux/macOS).
Fix: Use `pip install virtualenvwrapper-win` and follow its specific setup instructions for Windows Command Prompt.

Install

pip install virtualenvwrapper Basic Installation
# Add these lines to your shell startup file (~/.bashrc, ~/.zshrc, or ~/.profile) export WORKON_HOME=$HOME/.virtualenvs mkdir -p $WORKON_HOME export VIRTUALENVWRAPPER_PYTHON=$(which python3) # Or the path to your desired python interpreter source $(python3 -m site --user-base)/bin/virtualenvwrapper.sh Shell Configuration (Linux/macOS)

Quickstart

This quickstart guides you through installing virtualenvwrapper, configuring your shell, creating your first virtual environment, installing a package, and switching between environments. It's crucial to correctly source the virtualenvwrapper.sh script in your shell's startup file.

# 1. Install virtualenvwrapper (if not already done)
pip install virtualenvwrapper

# 2. Add configuration to your shell startup file (e.g., ~/.bashrc or ~/.zshrc)
#    Replace '/usr/bin/python3' with the path to your desired Python 3 interpreter if different.
#    Replace 'virtualenvwrapper.sh' path if it's not found in default user-base bin.
#    Example for .bashrc or .zshrc:
#    export WORKON_HOME=$HOME/.virtualenvs
#    mkdir -p $WORKON_HOME
#    export VIRTUALENVWRAPPER_PYTHON=$(which python3)
#    source $(python3 -m site --user-base)/bin/virtualenvwrapper.sh

# 3. Reload your shell configuration (or open a new terminal)
source ~/.bashrc # or source ~/.zshrc

# 4. Create a new virtual environment
mkvirtualenv myproject_env

# 5. Verify the active environment
workon

# 6. Install packages in the active environment
pip install requests

# 7. Deactivate the environment
deactivate

# 8. Switch to another environment (or reactivate)
workon myproject_env

view raw JSON →