Bash helpers for navigating and managing Python VirtualEnvs.
virtualenv bash helper closest virtual environment create mkenv destroy rmenv change chenv activate discover find findenv list lsenv cdenv , python , shell , virtualenv
pip install envie==0.4.36
Envie is a set of shell utilities (in
bash) aiming to increase your productivity
when dealing with mundane Python virtual environment tasks, like creating, destroying,
listing/discovering, and switching/activating environments.
Where Envie really shines is auto-discovery, auto-activation and auto-creation of virtual envs relevant to your project (or executable). It holds no assumptions on virtual env dir location in relation to your code (or working directory), but works best if they're near (nested, in level, or a few levels up).
I like to keep my virtual environments close to source (especially in production). With hundreds of projects on disk, this enables me to keep environment dir names short and project-relevant (since a project can have several environments, e.g. dev, prod, test). Also, environments are easy to locate, update, or rebuild (maintain in general).
If you structure your files/projects in any of the ways depicted in Fig 1. below, you'll find Envie particularly helpful.
work work /srv │ │ │ ├── plucky ├── jsonplus ├── production │ ├── env <-- │ ├── .git │ ├── website │ ├── plucky │ ├── django │ │ ├── pythonenv <-- │ ├── tests │ │ ├── env │ │ ├── var │ └── ... │ │ │ ├── dev <-- │ │ └── src │ │ │ │ └── prod <-- : : ├── .git ├── blog │ │ ├── tests : : └── ... │ ├── .env <-- │ │ │ ├── env <-- . . : ├── .git : : : ├── test_1.py : ├── _posts : : : └── ... . └── ... . . . (a) env in level with src (b) env nested under src (c) env one level above src Figure 1. Several ways to keep your environments local to the code.
To activate the closest virtual environment in vicinity, just type
envie (Fig 1.a and 1.c):
~/work/plucky$ envie Activated virtual environment at 'env'. /srv/production/website/src$ envie Activated virtual environment at '../pythonenv'.
If several equally close environments are found (Fig 1.b), you'll be prompted to select the exact env. But, you can avoid it with a cunning use of fuzzy-filtering, for example:
~/work/jsonplus$ envie dev Activated virtual environment at 'django/env/dev'.
Discovery and filtering have no limits on depth, so you can activate your project environment like:
~$ envie plus dev Activated virtual environment at 'work/jsonplus/django/env/dev'.
Sometimes you don't care about activating the relevant environment in your shell. You just want your script to run in the correct env. Easy peasy (ref. Fig 1.b):
~/work/jsonplus$ envie ./django/tests/test_1.py Activated virtual environment at 'django/tests/env'. # running test ...
It doesn't have to be a Python script:
~/work/plucky$ envie run make test Activated virtual environment at 'env'. # running 'make' with python from env
And it works from a hash bang too:
You can even activate the closest environment after the fact, from your Python program (changing the environment from whatever was current — to the closest, relative to the script):
#!/usr/bin/python import envie.activate_closest
Sure, you can use
virtualenv --python=python3 env, but isn't this simpler?
$ envie create -3 # or, shorter: $ mkenv3
And how about also installing your pip requirements in one go?
$ mkenv -r dev-requirements.txt env/dev
Or, creating a temporary/throw-away environment with some packages installed, then hacking in an interactive Python session, and finally destroying the complete environment upon exit:
$ mkenv -t -p requests -p 'plucky>=0.4' && python && rmenv -f
Activation of the closest environment is predicated on the discovery of the existing virtual
environments below a certain directory with
lsenv (envie list), and on the up-the-tree
findenv (envie find):
~/work$ lsenv plucky/env blog/.env jsonplus/django/env/dev ...
envie is packaged and distributed as a Python package.
You can install it system-wide (or user-local, see Install docs):
$ sudo pip install envie $ envie config # don't forget to source envie: $ . ~/.bashrc # or just open a new shell
After install, be sure to run a (short and interactive) configuration procedure with
If in doubt, go with the defaults. Running config is optional, but recommended.
It'll, for example, allow to you easily add Envie sourcing statement to your
(enabling Bash completion and alias functions), and to activate environments indexing
(enabling faster search with
envie uses the
find command to search for environments. That
approach is pretty fast when searching shallow trees. However, if you have
deeper directory trees, it's often faster to use a pre-built directory index
locate command). To configure a combined
locate/find approach to
When index is enabled, the combined approach is used by default (if not overriden with
-l switches). In the combined approach,
locate start searching
in parallel and vie for producing results first. However,
find is given only 400ms to finish
before being terminated, thusly producing
locate-based results for deeper trees faster
(but potentially incomplete if index was stale).
Run all test suites locally with:
$ make test
(after cloning the repo.)
envie [-1] [-f|-l] [<basedir>] [<keywords>](alias
findenv), optionally filtered by a list of
<keywords>. Start looking in
envie create [-2|-3|-e <pyexec>] [-r <pip_req>] [-p <pip_pkg>] [-a] [<envdir> | -t](alias
<envdir>(or in a temporary dir,
-t) based on a Python interpreter
<pyexec>, optionally installing Pip requirements from
envie list [-f|-l] [<dir>] [<keywords>](alias
<dir>directory, optionally filtered with a list of
envie find [-f|-l] [<dir>] [<keywords>](alias
<dir>; optionally filtered with a list of
envie python <script>
scriptin the closest virtual environment.
envie run <command>
command/builtin/file/alias/functionin the closest virtual environment.
<script>file, run the
<script>, and destroy the environment afterwards.
envie find -h, or
Documentation is hosted by ReadTheDocs, latest version being available at envie.rtfd.io.