conda.el
conda.el copied to clipboard
Emacs helper library (and minor mode) to work with conda environments
conda.el
Emacs library for working with conda environments, largely ported from virtualenvwrapper.el.
what it does
- Makes Python shells, interactive shells, eshell, anaconda-mode, and so on aware of your conda environments
- Detects and auto-activates the right conda environment for a particular buffer.
running tests
Using makem.sh
:
make v=v sandbox=/tmp install-deps=t test-ert
make v=v`
basic usage
-
Install conda (included if you have installed Anaconda or Miniconda)
-
Install from MELPA (
M-x package-install conda
), or just putconda.el
on your load path. -
Add it to your configuration (e.g. your
.emacs
orinit.el
). Something like this should work:(require 'conda) ;; if you want interactive shell support, include: (conda-env-initialize-interactive-shells) ;; if you want eshell support, include: (conda-env-initialize-eshell) ;; if you want auto-activation (see below for details), include: (conda-env-autoactivate-mode t) ;; if you want to automatically activate a conda environment on the opening of a file: (add-to-hook 'find-file-hook (lambda () (when (bound-and-true-p conda-project-env-path) (conda-env-activate-for-buffer))))
-
If your Anaconda installation is anywhere other than the default (
~/.anaconda3
) then set theconda-anaconda-home
custom variable to the installation path. For instance, if you installed miniconda via Homebrew on macOS, this should work:(custom-set-variables '(conda-anaconda-home "/usr/local/Caskroom/miniconda/base/"))
Also, if you have configured your Anaconda environment directory differently from the default (i.e. not relative to the Anaconda installation), you additionally need to set the
conda-env-home-directory
. For example, if it's at~/anaconda3/
(while your main Anaconda installation might be at/opt/anaconda
):(setq conda-env-home-directory (expand-file-name "~/anaconda3/"))
Especially if you've changed from the default configuration, be sure to double-check that your Conda environments are correctly located. The default subdirectory is
envs
, so if yourconda-env-home-directory
is~/anaconda3
then by default environments will be looked for in~/anaconda3/envs
. You can change this with theconda-env-subdirectory
setting:(setq conda-env-home-directory (expand-file-name "~/anaconda3/") ;; as in previous example; not required conda-env-subdirectory "myenvs")
Now environments will be searched for under
~/anaconda3/myenvs
. -
Use
M-x conda-env-activate
to activate conda environments andM-x conda-env-deactivate
to deactivate them. You can also useM-x conda-env-activate-for-buffer
to try and detect the correct conda environment for a buffer, or use theconda-env-autoactivate-mode
minor mode to do this automatically (see below for more details).
what do activating and deactivating actually do?
As with virtualenvwrapper.el, activating a conda environment does:
- Sets
python-shell-virtualenv-path
to the environment's directory so that when you open a new python shell, it is aware of the environment's installed packages and modules. - The environment's
bin
directory is prepended to thePATH
environment variable and Emacs' internalexec-path
, so that when a process is launched from Emacs it is aware of any executables installed in the virtualenv (e.gpy.test
,pep8
, etc.). This comes in handy for FlyCheck to correctly lint your code, or to useM-! nosetests
to run your tests, and so on. - The
VIRTUAL_ENV
environment variable is set to the environment's directory so any tools that depend on this variable function correctly (such as jedi). -
pythonic-activate
is called on the environment to ensure any other Python- related code is initialized with the right working path, version of Python, and so on.
When you deactivate, all these things are undone. You can safely
modify your PATH
and exec-path
while a virtualenv is active and
expect the changes not to be destroyed.
This covers everything except interactive shells, which are covered in the next section.
shells
This thing supports two types of interactive shells, the
eshell
and the
interactive subshell
(what you get when you do M-x shell
).
interactive shell
Support for interactive shell is turned on by calling conda-env-initialize-interactive-shell
.
After this is done, whenever you call shell
, the shell will start in the
correct conda environment. Note that changing the environment in Emacs will not
affect any running shells and vice-versa; they are independent processes.
WARNINGS
This feature is a pretty big hack and works by
advising
the shell
function. This works fine if you haven't otherwise tricked
out or advised it, but if this is the case it may break.
eshell
Support for eshell is turned on by calling conda-env-initialize-eshell
. After
doing this, any new eshells you launch will be in the correct environment and
have access to installed executables, etc. The mode also provides a variety of
virtualenvwrapper-like commands that work identically to their bash/zsh
counterparts (described in detail below). Note that in contrast to how
interactive shells work, Eshell shares an environment with Emacs, so if you
activate or deactivate in one, the other is affected as well. Note that this
requires the variable eshell-modify-global-environment
to be set to true --
running conda-env-initialize-eshell
causes this to occur.
command reference
The commands this mode provides are prefixed with conda-
(right now, the majority
start with conda-env-
since they deal with environments). All commands can be
called interactively using M-x
. Many of these commands have also been aliased
without prefixes as eshell functions, so you can call them on the eshell just as
you would in bash or zsh. For example:
eshell> activate myenv
eshell> deactivate
All will do what would expect.
conda-env-activate
Prompts for the name of a conda environment and activates it as described above.
Can also be called noninteractively as (conda-env-activate "<NAME>")
.
conda-env-deactivate
Deactivates the current conda environment, undoing everything that conda-env-activate
did. This can also be called noninteractively as (conda-env-deactivate)
.
conda-env-list
List all available conda environments, in a temp buffer.
useful macros
There is a conda-with-env
macro, which takes the name of a conda environment and
then any number of forms and executes those forms with that environment active.
Since it's common to want to execute shell commands, there is a convenience macro
conda-with-env-shell-command
, which takes a string, interpreted as a shell
command, and do exactly what you'd expect. So for example, you can do
(conda-with-env-shell-command "myenv" "conda install pep8")
to install pep8
in the myenv
conda environment. It can also be called interactively and will
prompt for a command to run if so.
keybindings
Just like virtualenvwrapper.el
, no keybindings defined here. Do what you like!
automatically activating a virtualenv in a particular project
It's also common to want to have an environment automatically activated when you
open a file in a certain project. This can be done with the conda-env-autoactivate-mode
minor mode, which will:
- check for a per-directory local variable
setting the
conda-project-env-path
variable with either the name or the full path to an existing conda environment - search up the directory tree for a file defining a conda environment, such
as an
environment.yml
file, and try to activate the named environment
displaying the currently active environment on the mode line
The name of the currently active conda environment is stored in the variable
conda-env-current-name
. If you want to have it displayed on your customized
mode line you can just add (:exec (list conda-env-current-name)))
somewhere
in your mode-line-format
. If you don't customize your mode line and just want
to have the current virtualenv displayed, you can do:
(setq-default mode-line-format (cons '(:exec conda-env-current-name) mode-line-format))
eshell prompt customization
You might also want to have the name of your current conda environment appear on
the eshell prompt. You can do this by a pretty similar mechanism, just include
conda-env-current-name
in your eshell-prompt-function
somewhere.
More about customizing the eshell prompt on the EmacsWiki.
bugs / comments / contributions
Please open an issue or a PR! I'm happy to pull in contributions or take suggestions for improvements.