Commands Reference

Calling Envie

The envie script (or a shell function) has three calling forms – two “shortcut” forms, and general/all-purpose form:

1. find & activate

envie [OPTIONS] [DIR] [KEYWORDS]

The first form interactively activates the closest environment (relative to DIR, or the current working directory, filtered by KEYWORDS). If a single closest environment is detected, it is auto-activated. This calling form is basically an alias for chenv -v [DIR] [KEYWORDS]. For options and details on environments discovery/selection, see chenv below.

2. run python script

envie SCRIPT

The second form is a shorthand for executing python scripts in the closest virtual environment, without the need for a manual env activation. It’s identical in behaviour to envie python SCRIPT (see below), but more convenient for a hash bang use:

#!/usr/bin/env envie
# Python script here will be executed in the closest virtual env

3. general

envie {create [ENV] | remove |
       list [DIR] [KEYWORDS] | find [DIR] [KEYWORDS] |
       python [SCRIPT] | run CMD |
       index | config | help | --help | --version}

The third is a general form as it explicitly exposes all commands (for virtual env creation, removal, discovery, etc.) Most of these commands have a shorter alias you’ll probably prefer in everyday use (like mkenv, lsenv, findenv, chenv, rmenv, etc).

envie / chenv - Interactively activate the closest virtual environment

Interactively activate the closest Python virtual environment relative to DIR (or .)
A list of the closest environments is filtered by KEYWORDS. Separate KEYWORDS with --
if they start with a dash, or a dir with the same name exists.

Usage:
    chenv [-1] [-f|-l] [-v] [-q] [DIR] [--] [KEYWORDS]
    envie ...

Options:
    -1            activate only if a single closest env found, abort otherwise
    -f, --find    use only 'find' for search
    -l, --locate  use only 'locate' for search
    -v            be verbose: show info messages (path to activated env)
    -q            be quiet: suppress error messages

chenv command uses findenv to discover all virtual environments in DIR‘s vicinity (searching below DIR, then dir-by-dir up until at least one virtual env is found), and then fuzzy-filters that list with a list of KEYWORDS given. If a single virtual environment is found, it’s automatically activated. If multiple environments are found, user chooses the environment from a list.

Examples

Suppose you have a directory structure like this:

work
├── plucky
│   ├── env
│   │   ├── dev
│   │   └── prod
│   └── src
├── jsonplus
│   ├── pythonenv
│   ├── src
│   └── var

Starting from base directory work, we can activate jsonplus environment with:

~/work$ envie js
Activated virtual environment at 'jsonplus/pythonenv'.

Or, starting from a project root at work/jsonplus/src, just type:

~/work/jsonplus/src$ envie
Activated virtual environment at '../pythonenv'.

When your query matches multiple environments, you’ll get a prompt:

~/work$ envie plucky
1) plucky/env/dev
2) plucky/env/prod
#? 2
Activated virtual environment at 'plucky/env/prod'.

But you can avoid it by being a bit more specific:

~/work$ envie prrrod
Activated virtual environment at 'plucky/env/prod'.

(Notice we had a typo here, prrrod.)

envie create / mkenv - Create a new virtual environment

Create Python (2/3) virtual environment in DEST_DIR based on PYTHON.

Usage:
    mkenv [-2|-3|-e PYTHON] [-r PIP_REQ] [-p PIP_PKG] [-a] [-t] [DEST_DIR] [-- ARGS_TO_VIRTUALENV]
    mkenv2 [-r PIP_REQ] [-p PIP_PKG] [-a] [-t] [DEST_DIR] ...
    mkenv3 [-r PIP_REQ] [-p PIP_REQ] [-a] [-t] [DEST_DIR] ...
    envie create ...

Options:
    -2, -3      use Python 2, or Python 3
    -e PYTHON   use Python accessible with PYTHON name,
                like 'python3.5', or '/usr/local/bin/mypython'.
    -r PIP_REQ  install pip requirements in the created virtualenv,
                e.g. '-r dev-requirements.txt'
    -p PIP_PKG  install pip package in the created virtualenv,
                e.g. '-p "Django>=1.9"', '-p /var/pip/pkg', '-p "-e git+https://gith..."'
    -a          autodetect and install pip requirements
                (search for the closest 'requirements.txt' and install it)
    -t          create throw-away env in /tmp
    -v[v]       be verbose: show virtualenv&pip info/debug messages
    -q[q]       be quiet: suppress info/error messages

This command creates a new Python virtual environment (using the virtualenv tool) in the optionally supplied destination directory DEST_DIR. Default destination is env in the current directory, but that default can be overriden via config variable _ENVIE_DEFAULT_ENVNAME).

The default Python interpreter (executable used in a new virtual env) is defined with the config variable _ENVIE_DEFAULT_PYTHON and if not specified otherwise, it defaults to system python. Python executable can always be explicitly specified with -e parameter, e.g: -e /path/to/python, or -e python3.5. The shorthand flags -2 and -3 will select the default Python 2 and Python 3 interpreters available, respectively.

Tip

You can use aliases mkenv2 and mkenv3 instead of mkenv -2 and mkenv -3, respectively.

To (pre-)install a set of Pip packages (requirements) in the virtual env created, you can use -r and -p options, like: -r requirements.txt and -p package/archive/url. The former will install requirements from a given file (or files, if option is repeated), and the latter will install a specific Pip package (or packages, if option repeated). The -p option supports all pip-supported formats: requirement specifier, VCS package URL, local package path, or archive path/URL:

  • -p requests, -p "jsonplus>=0.6",
  • -p /path/to/my/local/package,
  • -p "-e git+https://github.com/randomir/plucky.git#egg=plucky".

If a standard name for requirements file is used in your project (requirements.txt), you can use the -a flag to find and auto-install the closest requirements below the CWD.

Throw-away or temporary environment is created with -t flag. The location and name of the virtual environment are chosen randomly with the mktemp (something like /tmp/tmp.4Be8JJ8OJb). When done with hacking in a throw-away env, simply destroy it with rmenv -f.

Tip

Throw-away environments are great for short-lived experiments, for example:

$ mkenv3 -t -p requests -p plucky && python && rmenv -fv
Creating Python virtual environment in '/tmp/tmp.ial0H5kZvu'.
Using Python 3.5.2+ (/usr/bin/python3).
Virtual environment ready.
Installing Pip requirements: requests plucky
Pip requirements installed.
Python 3.5.2+ (default, Sep 22 2016, 12:18:14)
[GCC 6.2.0 20160927] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> import requests, plucky
>>> plucky.pluck(requests.get('https://api.github.com/users/randomir/repos').json(), 'name')
['blobber', 'dendritic-growth-model', 'envie', 'joe', 'jsonplus', 'python-digitalocean', ...]
>>> exit()
VirtualEnv removed: /tmp/tmp.ial0H5kZvu

Examples

Starting from a base directory ~/work, let’s create Python 2 & 3 virtual environments for our new project yakkety:

~/work$ mkenv3 yakkety/env/dev
Creating Python virtual environment in 'yakkety/env/dev'.
Using Python 3.5.2+ (/usr/bin/python3).
Virtual environment ready.
(dev) ~/work$

(dev) ~/work$ mkenv2 yakkety/env/dev
Creating Python virtual environment in 'yakkety/env/prod'.
Using Python 2.7.12+ (/usr/bin/python2).
Virtual environment ready.
(prod) ~/work$

Note here (1) directory structure is recursively created, and (2) active environment does not interfere with Python interpreter discovery.

We can create a temporary environment with dev version of package installed from GitHub source:

$ mkenv -tp "-e git+https://github.com/randomir/plucky.git#egg=plucky"

envie remove / rmenv - Delete the active virtual environment

Remove (delete) the base directory of the active virtual environment.

Usage:
    rmenv [-f] [-v]
    envie remove ...

Options:
    -f    force; don't ask for permission
    -v    be verbose

rmenv will remove a complete virtual env directory tree of the active environment (defined with shell variable $VIRTUAL_ENV), or fail otherwise. To avoid prompting for confirmation, supply the -f flag, and to print the directory removed, use the -v switch.

envie list / lsenv [DIR] - List virtual environments below DIR

Find and list all virtualenvs under DIR, optionally filtered by KEYWORDS.

Usage:
    lsenv [-f|-l] [DIR [AVOID_SUBDIR]] [--] [KEYWORDS]
    envie list ...

Options:
    -f, --find    use only 'find' for search
    -l, --locate  use only 'locate' for search
                  (by default, try find for 0.4s, then failback to locate)
    -v            be verbose: show info messages
    -q            be quiet: suppress error messages

envie list searches down only, starting in DIR (defaults to .). The search method is defined with config, but it can be overriden with -f and -l to force find or locate methods respectively.

Fuzzy filtering. To narrow down the list of virtualenv paths, you can filter it by supplying KEYWORDS. Filtering algorithm is not strict and exclusive (like grep), but fuzzy and typo-forgiving.

It works like this: (1) all virtualenv paths discovered are split into directory components; (2) we try to greedily match all keywords to components by maximum similarity score; (3) paths are sorted by total similarity score; (4) the best matches are passed-thru – if there’s a tie, all best matches are printed.

When calculating similarity between directory name (path component) and a keyword, we assign: (1) maximum weight to a complete match (identity), (2) smaller, but still high, weight to a prefix match, and (3) the smallest (and variable) weight to a diff-metric similarity.

Examples

For an example, suppose you have a directory tree like this one:

├── trusty-tahr
│   ├── dev
│   └── prod
├── zesty-zapus
│   ├── dev
│   └── prod

To get all environments containing dev word:

$ lsenv dev
trusty-tahr/dev
zesty-zapus/dev

To get all trusty envs, you can either filter by trusty (or tahr, or hr, or t):

$ lsenv hr
trusty-tahr/dev
trusty-tahr/prod

or, list envs in ./trusty-tahr dir:

$ lsenv ./trusty-tahr
trusty-tahr/dev
trusty-tahr/prod

Combine it:

$ lsenv trusty-tahr pr
trusty-tahr/prod

or with several keywords:

$ lsenv z d
zesty-zapus/dev

envie find / findenv [DIR] - Find the closest virtual environment around DIR

Find and list all virtualenvs below DIR, or above if none found below.
List of virtualenv paths returned is optionally filtered by KEYWORDS.

Usage:
    findenv [-f|-l] [DIR] [--] [KEYWORDS]
    envie find ...

Options:
    -f, --find    use only 'find' for search
    -l, --locate  use only 'locate' for search
                  (by default, try find for 0.4s, then failback to locate)
    -v            be verbose: show info messages
    -q            be quiet: suppress error messages

Similar to envie list, but with a key distinction: if no environments are found below the starting DIR, the search is being expanded – level by level up – until at least one virtual environment is found.

Description of discovery methods (--find/--locate), as well as keywords filtering behaviour given for envie list/lsenv apply here also.

envie python / envie SCRIPT - Run Python SCRIPT in the closest virtual environment

Run a Python SCRIPT, or an interactive Python interpreter session in the closest virtual environment. Three calling forms are supported:

envie SCRIPT [ARGS]
The SCRIPT is explicitly executed with python from the closest environment. If multiple environments are found in the vicinity, operation is aborted.
envie python SCRIPT [ARGS]
Identical in behaviour to the above, but more explict.
envie python
A special no-script case, where an interactive Python session is started instead.

Hint

This command is basically a shortcut for:

chenv -1v && exec python [SCRIPT [ARGS]]

Examples

envie manage.py migrate

envie python tests.py --fast

envie run CMD - Run CMD in the closest virtual env

As a generalization of the envie python command above, this command will run anything that can be run, in the closest virtual environment. The CMD can be an executable (script) file, shell command, shell builtin, alias, or a shell function.

envie run CMD [ARGS]
Runs any executable construct CMD, optionally passing-thru arguments ARGS, inside the closest virtual environment. Fails when multiple environments are found in the vicinity.

Hint

Similarly to envie python, this command is basically a shortcut for:

chenv -1v && exec CMD [ARGS]

Examples

We can emulate the envie python command with:

envie run python /path/to/my/script

but also run shell functions which are sensitive to the Python virtual env:

envie run my_function

Moreover, we can run the apropriate python in the command mode:

envie run python -c 'import os; print(os.getenv("VIRTUAL_ENV"))'

envie config - Configure Envie

Listed here for completeness, configuration is described in detail under the Configure section.

envie index - (Re-)Index Environments

If Envie is configured to use locate for environments discovery, index can be rebuilt (updated via updatedb) with envie index. For more on find vs. locate methods, see here.

envie-tmp SCRIPT - Run SCRIPT in a temporary environment

Create a new temporary (throw-away) virtual environment, install requirements
specified, run the SCRIPT, and destroy the environment afterwards.

Usage:
    envie-tmp SCRIPT

Hashbang examples:

 1) no requirements (mkenv -t)

    #!/usr/bin/env envie-tmp

 2) installs reqs from the closest "requirements.txt" (mkenv -ta):

    #!/usr/bin/env envie-tmp
    # -*- requirements: auto -*-

 3) installs reqs from the specific Pip requirements files (relative to SCRIPT's dir)
    (mkenv -t -r REQ ...):

    #!/usr/bin/env envie-tmp
    # -*- requirements: ../base-requirements.txt ./dev-requirements.txt -*-

 4) specify the Python version to use, and install some Pip packages
    (mkenv -t -e PYTHON -p PKG ...):

    #!/usr/bin/env envie-tmp
    # -*- python-version: python3 -*-
    # -*- packages: plucky requests>=2.0 flask==0.12 -e/path/to/pkg -e. -*-