Registry / devops / virtualenvwrapper

virtualenvwrapper

library6.1.1pypypiunverified

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.

devops

pip install virtualenvwrapper

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · VIRTUALENVWRAPPER

virtualenvwrapper

devopspythonv6.1.1

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

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

virtualenvwrapper --version

Debug

Known issues

breakingPython 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.

affects: 6.0.0+

breakingThe `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.

affects: 6.0.0+

breakingSupport for `ksh` shell was dropped in virtualenvwrapper 6.x.

fix

Use a supported shell like `bash` or `zsh`.

affects: 6.0.0+

gotchaFor 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.

affects: Python 3.12+ (virtualenvwrapper 6.x)

gotchaWindows 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.

affects: All versions on Windows

Errors

Common errors & fixes

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.

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

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

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.

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`.

Upgrade

Version history

6.1.1latest on PyPI · released Oct 13, 2024

Audit

Dependencies

virtualenvrequiredvirtualenvwrapper builds upon and requires virtualenv.

virtualenv-cloneoptionalUsed for copying virtual environments.

stevedoreoptionalPlugin loading for extensions.

pbroptionalPackaging for virtualenvwrapper itself.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/python-virtualenvwrapper/virtualenvwrapper ↗

packagehttps://pypi.org/project/virtualenvwrapper/ ↗

homepagehttps://virtualenvwrapper.readthedocs.io/ ↗