For each development project I need a distinct environment so that any dependencies and alterations are isolated from the rest of the system. There are a variety of ways of doing this, from using environmental variables, through to chroots and virtual environments. Direnv automates activating a virtual environment - when I go to a project directory it activates the environment I need for that project. It's a two-stage process, I use virtualenvwrapper to create a virtual environment for each Python project, and then Direnv is used to automate executing the virtual environment.
Direnv is a general automation utility, its role is to alter the shell environment or run a script when the user enters a specific directory. It fulfils a similar role to other tools such as Autoenv, Smartcd, Zsh-autoenv etc. I started with Autoenv but it can't automatically deactivate an environment when the user leaves the project directory [1]. Direnv is able to do this, which makes it a more general automation utility. It plugs into the shell rather than over-riding cd which makes it more flexible. It's also compatible with Bash, Zsh, Tcsh or Fish.
Commands to be run when entering a target directory are stored in a .envrc file that's stored in the directory. To provide security direnv makes you authorise automatically executing this file the first time it sees it, and if there are any subsequent changes to the file it won't execute it until you re-authorise it. You can see the checksums in ~/.config/direnv/allow
Direnv is available on Github so can be installed directly from source. For Ubuntu and Debian users it's available in the repositories.
https://launchpad.net/ubuntu/+source/direnv
$ dpkg --install direnv_2.7.0-1_amd64.deb
To configure direnv we have to set it to automatically execute when our shell changes directory. It does this by hooking into the shell directly. For me that's Bash so the command to set this up is:
$ echo 'eval "$(direnv hook bash)"' >> ~/.bashrc
Execute a new shell and it will pull this hook in.
The second stage is to create a specific .envrc for the commands that you want it to automate. Change to the directory where you want the automation and do direnv edit.
For Python development I use Virtualenvwrapper to set-up project specific configurations. See my post Virtualenv and virtualenvwrapper for Python for more information. With direnv I can automate it so that when I change into the directory it executes the virtualenv I've set-up for that project, and when I leave the directory it resets my bash shell to normal.
Lets say I have a project in ~/projects/project1 which already has a virtualenv defined for it, I create an .envrc in that directory and put in:
source /usr/share/virtualenvwrapper/virtualenvwrapper.sh workon project1
I then run direnv allow which tells it that this .envrc is correct. Direnv will now automatically run that command when I enter the project directory.
When I use virtualenvwrapper it changes the shell prompt when I'm in a virtualenv so I have a visual indicator that I'm not in my standard environment. We can do the same by editing [2] .bashrc and adding:
show_virtual_env() { if [ -n "$VIRTUAL_ENV" ]; then virtualenv=`basename "$VIRTUAL_ENV"` echo "($virtualenv)" fi } PS1='$(show_virtual_env)'$PS1
That's it - every time I enter ~/projects/project1 it will execute the virtualenvwrapper project project1, and when I move out of the directory it will reset my environment:
~/workspace$ cd project1/ direnv: loading ~/.direnvrc direnv: loading .envrc direnv: using vwrapper direnv: export +VIRTUAL_ENV ~PATH ~/workspace/project1$ cd .. direnv: unloading
The only problems I've found so far is that the deactivate command doesn't work any more, you have to change to another directory rather than explicitly deactivating the environment - not sure why. It will also deactivate the environment if you use cdsitepackages as you're moving outside the directory hierarchy the .envrc is controlling, but that's fine for me.
Direnv comes with a standard library of automation functions that you can use. You can list them and read the documentation with:
$ direnv stdlib | less
The ones that appear the most useful are:
Aside from the direnv standard library it's possible to add your own shell functions in a ~/.direnvrc. This article by Puzan [3] covers adding a shell function for using virtualenv, so a simple extension to use virtualenvwrapper is below:
#export DIRENV_LOG_FORMAT= use_venv () { export VIRTUAL_ENV = "$ {HOME} /.virtualenvs/ $ { 1}" PATH_add "$ VIRTUAL_ENV / bin" } use_vwrapper () { source /usr/share/virtualenvwrapper/virtualenvwrapper.sh }
Then in an .envrc we can now do:
use vwrapper workon <somevirtualenv>
If you're using direnv to store secret environmental variables (ie login secrets) then the .envrc should not be stored in your version control [4].
$ git config --global core.excludesfile "~/.gitignore_global"
Then add to ~/.gitignore_global:
# Direnv stuff .direnv .envrc EXCL
The main resources I found for Direnv are:
With Direnv and Virtualenvwrapper my development set-up is completely automated. Just need to think what else I can automate now!
| [1] | The lead developer closed the long-running Issue asking for this feature after I reawakened it which is a pretty clear answer he considers it out of scope! |
| [2] | From Python direnv tips |
| [3] | From Direnv by Puzan |
| [4] | From Git - Direnv wiki |