Autoswitch Python Virtualenv
zsh-autoswitch-virtualenv is a simple and quick ZSH plugin that switches python virtualenvs automatically as you move between directories.
zsh-autoswitch-virtualenv also automatically detects and activates your Pipenv and Poetry projects without any setup necessary.
- How it Works
- More Details
- Pipenv and Poetry Integration
- Customising Messages
- Security Warnings
- Running Tests
How it Works
Simply call the
mkvenv command in the directory you wish to setup a
virtual environment. A virtual environment specific to that folder will
now activate every time you enter it.
zsh-autoswitch-virtualenv will detect python projects and remind
you to create a virtual environment. This mainly occurs if one of the following
is found in current the directory:
To create a virtual environment for that project, simply run
This command works as expected for all popular python project types
(virtualenvs, pipenv and poetry).
See the Commands section below for more detail.
Moving out of the directory will automatically deactivate the virtual
environment. However you can also switch to a default python virtual
environment instead by setting the
Internally this plugin simply works by creating a file named
which contains the name of the virtual environment created (which is the
same name as the current directory but can be edited if needed). There
is then a precommand hook that looks for a
.venv file and switches
to the name specified if one is found.
Autoswitch virtualenv also works automatically with projects which contains
.venv virtualenv directly created by the
python -m venv command.
For the case of pipenv projects, the plugin will look for a
and activates pipenv if it detects an existing virtual environment for it.
For the case of poetry projects, the plugin will look for a
and activates poetry if it detects an existing virtual environment for it.
NOTE: you may want to add
.venv to your
.gitignore in git
projects (or equivalent file for the Version Control you are using).
autoswitch-virtualenv requires virtualenv to be installed.
You will also need to make sure that
python (without a suffix; both Python 2 and 3 are supported) is available in your
virtualenv is installed, add one of the following lines to your
.zshrc file depending on the
package manager you are using:
antigen bundle "MichaelAquilina/zsh-autoswitch-virtualenv"
zgen load "MichaelAquilina/zsh-autoswitch-virtualenv"
Copy this repository to
is the directory with custom plugins of oh-my-zsh (read more):
git clone "https://github.com/MichaelAquilina/zsh-autoswitch-virtualenv.git" "$ZSH_CUSTOM/plugins/autoswitch_virtualenv"
Then add this line to your
.zshrc. Make sure it is before the line
Source the plugin shell script in your ~/.zshrc profile. For example
Pipenv and Poetry Integration
This plugin will also detect and auto activate virtualenvs made with
No action needs to be performed in projects where a poetry/pipenv project has already been setup.
Setup a new python project with autoswitching using the
$ cd my-python-project $ mkvenv Creating my-python-project virtualenv Found a requirements.txt. Install? [y/N]: Collecting requests (from -r requirements.txt (line 1)) Using cached requests-2.11.1-py2.py3-none-any.whl Installing collected packages: requests Successfully installed requests-2.11.1
This command also works as expected with both
Optionally, you can specify the python binary to use for this virtual environment
$ mkvenv --python=/usr/bin/python3
In fact any parameters passed to mkvenv will be passed to the relevant setup command.
The same applies to passing additional parameters to
pipenv install and
Autoswitching is smart enough to detect that you have traversed to a project subdirectory. So your virtualenv will not be deactivated if you enter a subdirectory.
$ cd my-python-project Switching virtualenv: my-python-project [Python 3.4.3+] $ cd src $ # Notice how this has not deactivated the project virtualenv $ cd ../.. Switching virtualenv: mydefaultenv [Python 3.4.3+] $ # exited the project parent folder, so the virtualenv is now deactivated
You can remove the virtual environment for a directory you are currently
in using the
rmvenv helper function:
$ cd my-python-project $ rmvenv Switching virtualenv: mydefaultenv [Python 2.7.12] Removing myproject...
This will delete the virtual environment in
.venv and remove the
.venv file itself. The
rmvenv command will fail if there is no
.venv file in the current directory:
$ cd my-non-python-project $ rmvenv No .venv file in the current directory!
rmvenv command also works as you would
expect with removing
Temporarily disables autoswitching of virtualenvs when moving between directories.
Re-enable autoswitching of virtualenvs (if it was previously disabled).
By default, the following message is displayed in bold when an alias is found:
Switching %venv_type: %venv_name [%py_version]
Where the following variables represent:
%venv_type- the type of virtualenv being activated (virtualenv, pipenv, poetry)
%venv_name- the name of the virtualenv being activated
%py_version- the version of python used by the virtualenv being activated
This default message can be customised by setting the
AUTOSWITCH_MESSAGE_FORMAT environment variable.
If for example, you wish to display your own custom message in red, you can add the
following to your
export AUTOSWITCH_MESSAGE_FORMAT="$(tput setaf 1)Switching to %venv_name 🐍 %py_version $(tput sgr0)"
$(tput setaf 1) generates the escape code terminals use for red foreground text.
$(tput sgr0) sets
the text back to a normal color.
You can read more about how you can use tput and terminal escape codes here: http://wiki.bash-hackers.org/scripting/terminalcodes
The following options can be configured by setting the appropriate variables within your
Setting a default virtual environment
You can set a default virtual environment to switch to when not in a python project by setting
the value of
AUTOSWITCH_DEFAULTENV to the name of a virtualenv. For example:
Setting a default python binary
You may specify a default python binary to use when creating virtualenvs
by setting the value of
AUTOSWITCH_DEFAULT_PYTHON. For example:
You may still override this default as usual by passing the --python parameter to the mkvenv command.
Autoswitch file name
By default, the .venv file (or virtualenv directory) is searched for in each directory in order to tell if a virtualenv should be automatically activated.
If this needs to be changed (e.g. it conflicts with something else) then it may be
changed by setting the value of
AUTOSWITCH_FILE. For example:
Default requirements file
You may specify a default requirements file to use when creating a virtualenv by
setting the value of
AUTOSWITCH_DEFAULT_REQUIREMENTS. For example:
If the value is set and the target file exists you will be prompted to install with that file each time you create a new virtualenv.
Set verbosity when changing environments
You can prevent verbose messages from being displayed when moving
between directories. You can do this by setting
a non-empty value.
Choosing where virtualenvs are stored
By default, virtualenvs created are placed in
$HOME/.virtualenvs - which is
the same location that the
virtualenvwrapper package uses.
If you wish to change this to another location, simply set the value of the
If you wish for virtual environments to be stored within each project directory then you can set the variable to use a relative path. For example:
Customising pip install invocation
By default mkvenv will install setup.py via pip in editable (i.e. development) mode.
To change this set
zsh-autoswitch-virtualenv will warn you and refuse to activate a virtual environment automatically in the following situations:
- You are not the owner of the
.venvfile found in a directory.
.venvfile has weak permissions. I.e. it is writable by other users on the system.
In both cases, the warnings should explain how to fix the problem.
These are security measures that prevents other, potentially malicious users, from switching you to a virtual environment you did not want to switch to.
Install zunit. Run
zunit in the root
directory of the repo.
$ zunit Launching ZUnit ZUnit: 0.8.2 ZSH: zsh 5.3.1 (x86_64-suse-linux-gnu) ✔ _check_venv_path - returns nothing if not found ✔ _check_venv_path - finds .venv in parent directories ✔ _check_venv_path - returns nothing with root path ✔ check_venv - Security warning for weak permissions
NOTE: It is required that you use a minimum zunit version of 0.8.2