README.rst
11071 bytes
1Autoswitch Python Virtualenv
2============================
3
4|CircleCI| |Release| |GPLv3|
5
6*zsh-autoswitch-virtualenv* is a simple and quick ZSH plugin that switches python
7virtualenvs automatically as you move between directories.
8
9*zsh-autoswitch-virtualenv* also automatically detects and activates your **UV**, **Poetry** and **Pipenv** projects
10without any setup necessary.
11
12* `How it Works`_
13* `More Details`_
14* Installing_
15* `Uv, Poetry and Pipenv Integration`_
16* Commands_
17* `Customising Messages`_
18* Options_
19* `Security Warnings`_
20* `Running Tests`_
21
22
23How it Works
24------------
25
26Simply call the ``mkvenv`` command in the directory you wish to setup a
27virtual environment. A virtual environment specific to that folder will
28now activate every time you enter it.
29
30``zsh-autoswitch-virtualenv`` detects Python projects when one of the
31following files is in the current directory:
32
33* setup.py
34* requirements.txt
35* Pipfile
36* poetry.lock
37* uv.lock
38
39To create a virtual environment for that project, simply run ``mkvenv``.
40This command works as expected for virtualenvs, UV, Pipenv, and Poetry projects.
41
42See the Commands_ section below for more detail.
43
44More Details
45------------
46
47Moving out of the directory will automatically deactivate the virtual
48environment. However you can also switch to a default python virtual
49environment instead by setting the ``AUTOSWITCH_DEFAULTENV`` environment
50variable.
51
52Internally this plugin simply works by creating a file named ``.venv``
53which contains the name of the virtual environment created (which is the
54same name as the current directory but can be edited if needed). There
55is then a precommand hook that looks for a ``.venv`` file and switches
56to the name specified if one is found.
57
58Autoswitch virtualenv also works automatically with projects which contains
59a ``.venv`` virtualenv directly created by the ``python -m venv`` command.
60
61For the case of pipenv projects, the plugin will look for a ``Pipfile``
62and activates pipenv if it detects an existing virtual environment for it.
63
64For the case of poetry projects, the plugin will look for a ``pyproject.toml``
65and activates poetry if it detects an existing virtual environment for it.
66
67**NOTE**: you may want to add ``.venv`` to your ``.gitignore`` in git
68projects (or equivalent file for the Version Control you are using).
69
70Installing
71----------
72
73``autoswitch-virtualenv`` requires Python 3 with the ``venv`` module available.
74Make sure that ``python3`` is available in your ``$PATH``, or configure
75``AUTOSWITCH_DEFAULT_PYTHON`` to use a different Python binary.
76
77Add one of the following lines to your ``.zshrc`` file depending on the
78package manager you are using:
79
80ZPlug_
81
82::
83
84 zplug "MichaelAquilina/zsh-autoswitch-virtualenv"
85
86Antigen_
87
88::
89
90 antigen bundle "MichaelAquilina/zsh-autoswitch-virtualenv"
91
92Zgen_
93
94::
95
96 zgen load "MichaelAquilina/zsh-autoswitch-virtualenv"
97
98zinit_
99
100::
101
102 zinit wait lucid for MichaelAquilina/zsh-autoswitch-virtualenv
103
104oh-my-zsh_
105
106Copy this repository to ``$ZSH_CUSTOM/plugins``, where ``$ZSH_CUSTOM``
107is the directory with custom plugins of oh-my-zsh `(read more) <https://github.com/robbyrussell/oh-my-zsh/wiki/Customization/>`_:
108
109::
110
111 git clone "https://github.com/MichaelAquilina/zsh-autoswitch-virtualenv.git" "$ZSH_CUSTOM/plugins/autoswitch_virtualenv"
112
113Then add this line to your ``.zshrc``. Make sure it is **before** the line ``source $ZSH/oh-my-zsh.sh``.
114
115::
116
117 plugins=(autoswitch_virtualenv $plugins)
118
119Manual Installation
120'''''''''''''''''''
121
122Source the plugin shell script in your `~/.zshrc` profile. For example
123
124::
125
126 source $HOME/zsh-autoswitch-virtualenv/autoswitch_virtualenv.plugin.zsh
127
128
129Uv, Poetry and Pipenv Integration
130---------------------------------
131
132This plugin will also detect and auto activate virtualenvs made with ``uv``, ``poetry`` or ``pipenv``.
133No action needs to be performed in projects where a uv/poetry/pipenv project has already been setup.
134
135Commands
136--------
137
138mkvenv
139''''''
140
141Setup a new python project with autoswitching using the ``mkvenv``
142helper command.
143
144::
145
146 $ cd my-python-project
147 $ mkvenv
148 Creating my-python-project virtualenv
149
150This command also works as expected with ``uv``, ``poetry``, and ``pipenv``.
151
152Optionally, you can specify the python binary to use for this virtual environment
153
154::
155
156 $ mkvenv --python=/usr/bin/python3
157
158
159The ``--python`` option selects the Python binary used to run ``python -m venv``.
160Use ``--verbose`` to show its output. Other parameters are passed to the relevant
161setup command, including ``uv sync``, ``pipenv install``, and ``poetry install``.
162
163Autoswitching is smart enough to detect that you have traversed to a
164project subdirectory. So your virtualenv will not be deactivated if you
165enter a subdirectory.
166
167::
168
169 $ cd my-python-project
170 Switching virtualenv: my-python-project [Python 3.4.3+]
171 $ cd src
172 $ # Notice how this has not deactivated the project virtualenv
173 $ cd ../..
174 Switching virtualenv: mydefaultenv [Python 3.4.3+]
175 $ # exited the project parent folder, so the virtualenv is now deactivated
176
177rmvenv
178''''''
179
180You can remove the virtual environment for a directory you are currently
181in using the ``rmvenv`` helper function:
182
183::
184
185 $ cd my-python-project
186 $ rmvenv
187 Switching virtualenv: mydefaultenv [Python 2.7.12]
188 Removing myproject...
189
190This will delete the virtual environment in ``.venv`` and remove the
191``.venv`` file itself. The ``rmvenv`` command will fail if there is no
192``.venv`` file in the current directory:
193
194::
195
196 $ cd my-non-python-project
197 $ rmvenv
198 No .venv file in the current directory!
199
200Similar to ``mkvenv``, the ``rmvenv`` command also works as you would
201expect with removing ``poetry`` and ``pipenv`` projects.
202
203disable_autoswitch_virtualenv
204'''''''''''''''''''''''''''''
205
206Temporarily disables autoswitching of virtualenvs when moving between
207directories.
208
209enable_autoswitch_virtualenv
210''''''''''''''''''''''''''''
211
212Re-enable autoswitching of virtualenvs (if it was previously disabled).
213
214Customising Messages
215--------------------
216
217By default, the following message is displayed in bold when an alias is found:
218
219::
220
221 Switching %venv_type: %venv_name [%py_version]
222
223Where the following variables represent:
224
225* ``%venv_type`` - the type of virtualenv being activated (virtualenv, pipenv, poetry)
226* ``%venv_name`` - the name of the virtualenv being activated
227* ``%py_version`` - the version of python used by the virtualenv being activated
228
229This default message can be customised by setting the ``AUTOSWITCH_MESSAGE_FORMAT`` environment variable.
230
231If for example, you wish to display your own custom message in red, you can add the
232following to your ``~/.zshrc``:
233
234::
235
236 export AUTOSWITCH_MESSAGE_FORMAT="$(tput setaf 1)Switching to %venv_name %py_version $(tput sgr0)"
237
238``$(tput setaf 1)`` generates the escape code terminals use for red foreground text. ``$(tput sgr0)`` sets
239the text back to a normal color.
240
241You can read more about how you can use tput and terminal escape codes here:
242http://wiki.bash-hackers.org/scripting/terminalcodes
243
244
245Options
246-------
247
248The following options can be configured by setting the appropriate variables within your ``~/.zshrc`` file.
249
250**Setting a default virtual environment**
251
252You can set a default virtual environment to switch to when not in a python project by setting
253the value of ``AUTOSWITCH_DEFAULTENV`` to the name of a virtualenv. For example:
254
255::
256
257 export AUTOSWITCH_DEFAULTENV="mydefaultenv"
258
259**Setting a default python binary**
260
261You may specify a default python binary to use when creating virtualenvs
262by setting the value of ``AUTOSWITCH_DEFAULT_PYTHON``. For example:
263
264::
265
266 export AUTOSWITCH_DEFAULT_PYTHON="/usr/bin/python3"
267
268You may still override this default as usual by passing the --python parameter to
269the mkvenv command.
270
271**Autoswitch file name**
272
273By default, the `.venv` file (or virtualenv directory) is searched for in each
274directory in order to tell if a virtualenv should be automatically activated.
275
276If this needs to be changed (e.g. it conflicts with something else) then it may be
277changed by setting the value of ``AUTOSWITCH_FILE``. For example:
278
279::
280
281 export AUTOSWITCH_FILE=".autoswitch"
282
283**Set verbosity when changing environments**
284
285You can prevent verbose messages from being displayed when moving
286between directories. You can do this by setting ``AUTOSWITCH_SILENT`` to
287a non-empty value.
288
289**Choosing where virtualenvs are stored**
290
291By default, virtualenvs created are placed in ``$HOME/.virtualenvs`` - which is
292the same location that the ``virtualenvwrapper`` package uses.
293
294If you wish to change this to another location, simply set the value of the
295environment variable ``AUTOSWITCH_VIRTUAL_ENV_DIR``.
296
297If you wish for virtual environments to be stored within each project directory
298then you can set the variable to use a relative path. For example:
299
300::
301
302 export AUTOSWITCH_VIRTUAL_ENV_DIR=".virtualenv"
303
304**Customising pip install invocation**
305
306By default, ``mkvenv`` installs Pipenv projects in editable mode. To use a full
307Pipenv install instead, set ``AUTOSWITCH_PIPINSTALL`` to ``FULL``.
308
309Security Warnings
310-----------------
311
312zsh-autoswitch-virtualenv will warn you and refuse to activate a virtual
313environment automatically in the following situations:
314
315- You are not the owner of the ``.venv`` file found in a directory.
316- The ``.venv`` file has weak permissions. I.e. it is writable by other users on the system.
317
318In both cases, the warnings should explain how to fix the problem.
319
320These are security measures that prevents other, potentially malicious
321users, from switching you to a virtual environment you did not want to
322switch to.
323
324Running Tests
325-------------
326
327Install `zunit <https://zunit.xyz/>`__. Run ``zunit`` in the root
328directory of the repo.
329
330::
331
332 $ zunit
333 Launching ZUnit
334 ZUnit: 0.8.2
335 ZSH: zsh 5.3.1 (x86_64-suse-linux-gnu)
336
337 ✔ _check_venv_path - returns nothing if not found
338 ✔ _check_venv_path - finds .venv in parent directories
339 ✔ _check_venv_path - returns nothing with root path
340 ✔ check_venv - Security warning for weak permissions
341
342NOTE: It is required that you use a minimum zunit version of 0.8.2
343
344
345.. _Zplug: https://github.com/zplug/zplug
346
347.. _Antigen: https://github.com/zsh-users/antigen
348
349.. _ZGen: https://github.com/tarjoilija/zgen
350
351.. _zinit: https://github.com/zdharma-continuum/zinit
352
353.. _oh-my-zsh: https://github.com/robbyrussell/oh-my-zsh
354
355.. |CircleCI| image:: https://circleci.com/gh/MichaelAquilina/zsh-autoswitch-virtualenv.svg?style=svg
356 :target: https://circleci.com/gh/MichaelAquilina/zsh-autoswitch-virtualenv
357
358.. |Release| image:: https://badge.fury.io/gh/MichaelAquilina%2Fzsh-autoswitch-virtualenv.svg?icon=si%3Agithub
359 :target: https://github.com/MichaelAquilina/zsh-autoswitch-virtualenv/tags
360
361.. |ASCIICAST| image:: https://asciinema.org/a/ciDroIzqcC14VEeXMkqdRbvXf.svg
362 :target: https://asciinema.org/a/ciDroIzqcC14VEeXMkqdRbvXf
363
364.. |GPLv3| image:: https://img.shields.io/badge/License-GPL%20v3-blue.svg
365 :target: https://www.gnu.org/licenses/gpl-3.0