{"id":8763,"library":"virtualenvwrapper","title":"virtualenvwrapper","description":"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.","status":"active","version":"6.1.1","language":"en","source_language":"en","source_url":"https://github.com/python-virtualenvwrapper/virtualenvwrapper","tags":["virtual environments","development workflow","shell scripts","python","devops"],"install":[{"cmd":"pip install virtualenvwrapper","lang":"bash","label":"Basic Installation"},{"cmd":"# Add these lines to your shell startup file (~/.bashrc, ~/.zshrc, or ~/.profile)\nexport WORKON_HOME=$HOME/.virtualenvs\nmkdir -p $WORKON_HOME\nexport VIRTUALENVWRAPPER_PYTHON=$(which python3) # Or the path to your desired python interpreter\nsource $(python3 -m site --user-base)/bin/virtualenvwrapper.sh","lang":"bash","label":"Shell Configuration (Linux/macOS)"}],"dependencies":[{"reason":"virtualenvwrapper builds upon and requires virtualenv.","package":"virtualenv"},{"reason":"Used for copying virtual environments.","package":"virtualenv-clone","optional":true},{"reason":"Plugin loading for extensions.","package":"stevedore","optional":true},{"reason":"Packaging for virtualenvwrapper itself.","package":"pbr","optional":true}],"imports":[],"quickstart":{"code":"# 1. Install virtualenvwrapper (if not already done)\npip install virtualenvwrapper\n\n# 2. Add configuration to your shell startup file (e.g., ~/.bashrc or ~/.zshrc)\n#    Replace '/usr/bin/python3' with the path to your desired Python 3 interpreter if different.\n#    Replace 'virtualenvwrapper.sh' path if it's not found in default user-base bin.\n#    Example for .bashrc or .zshrc:\n#    export WORKON_HOME=$HOME/.virtualenvs\n#    mkdir -p $WORKON_HOME\n#    export VIRTUALENVWRAPPER_PYTHON=$(which python3)\n#    source $(python3 -m site --user-base)/bin/virtualenvwrapper.sh\n\n# 3. Reload your shell configuration (or open a new terminal)\nsource ~/.bashrc # or source ~/.zshrc\n\n# 4. Create a new virtual environment\nmkvirtualenv myproject_env\n\n# 5. Verify the active environment\nworkon\n\n# 6. Install packages in the active environment\npip install requests\n\n# 7. Deactivate the environment\ndeactivate\n\n# 8. Switch to another environment (or reactivate)\nworkon myproject_env","lang":"bash","description":"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."},"warnings":[{"fix":"Ensure you are using Python 3.8+ and that VIRTUALENVWRAPPER_PYTHON points to a Python 3 interpreter.","message":"Python 2 support was formally dropped in virtualenvwrapper 6.x. Attempts to use it with Python 2 will fail or lead to unexpected behavior.","severity":"breaking","affected_versions":"6.0.0+"},{"fix":"This feature is no longer supported. Manage site-packages inclusion when creating the virtual environment using virtualenv's options directly.","message":"The `toggleglobalsitepackages` command was removed in virtualenvwrapper 6.x because the underlying capability was removed from virtualenv itself.","severity":"breaking","affected_versions":"6.0.0+"},{"fix":"Use a supported shell like `bash` or `zsh`.","message":"Support for `ksh` shell was dropped in virtualenvwrapper 6.x.","severity":"breaking","affected_versions":"6.0.0+"},{"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.","message":"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`.","severity":"gotcha","affected_versions":"Python 3.12+ (virtualenvwrapper 6.x)"},{"fix":"Use `pip install virtualenvwrapper-win` and follow its specific setup instructions for Windows Command Prompt.","message":"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).","severity":"gotcha","affected_versions":"All versions on Windows"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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.","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`.","error":"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."},{"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`).","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.","error":"-bash: /usr/local/bin/virtualenvwrapper.sh: No such file or directory"},{"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).","cause":"The `virtualenvwrapper.sh` script, which defines these commands, has not been properly sourced into your current shell session.","error":"mkvirtualenv: command not found"},{"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`.","cause":"When using `mkproject`, the directory specified by `PROJECT_HOME` or the target project directory does not exist.","error":"ERROR: Project directory '/path/to/project' does not exist. Create it or set PROJECT_HOME to an existing directory."}]}