Anaconda Environments
=====================

Anaconda Enterprise Notebooks runs on 
:doc:`Anaconda </anaconda/index>`. Anaconda 
supports multiple versions of Python and associated packages. An 
environment generally includes one version of Python or R language 
and some packages.

The ability to have a custom environment for your project is one of the
most powerful features of Anaconda Enterprise Notebooks.

A project environment is integrated with the project so all project 
apps are aware of it and all project members have access to it.

This is an introduction to conda environments specifically for AEN users. 
See `conda <http://conda.pydata.org/docs/>`_ for full documentation on 
using conda, as well as cheat sheets, a conda test drive, and command 
reference. 

Creating
~~~~~~~~

Use the ``conda`` command in a terminal app to create new environments 
within your Anaconda
Enterprise Notebooks account. In Anaconda Enterprise Notebooks, all
new environments created with conda automatically include Python,
Jupyter Notebooks and pip. You can specify any other packages you want
included in your new environment.

TIP: By default, conda creates the new environment in your project's "env"
directory so all team members have access to the new environment. You can 
limit their read, write and/or execute permission from the Workbench app, 
select the notebook name then from the drop-down menu that appears, select 
Permissions. See the :doc:`Workbench <workbench>` page for more information.

EXAMPLE:

Create a new environment named "WeatherModel" that contains 
Python, NumPy, pip and Jupyter Notebooks. This will be in your 
project's "env" directory. 

Start by logging onto AEN and opening a project. This opens your 
project dashboard. 

Next, from your project's dashboard, open the terminal application and 
enter the following::

    conda create -n WeatherModel numpy

Remember, Python, pip and Jupyter Notebooks are automatically installed in 
each new environment. This is why we need to specify only NumPy.

To make this new environment your default environment, in your terminal app enter:: 

    source activate WeatherModel

When finished with your notebook, to deactivate this new environment, 
in your terminal app simply enter::

    source deactivate

TIP: If you prefer to remain in the Notebook interface, you can create, activate,
install packages and deactivate environments from within a notebook file menu by 
selecting the conda file tab and adding it with the "plus sign" icon. Then search 
for "numpy" in the package search box and click the Install button. Either way,  
the environment is located in the project's same "env" directory. 


Using environments in notebooks
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Whether you have created an environment using conda like above, or created one from 
the conda file tab, the instructions for using an environment in that notebook 
are the same. 

When working in a notebook, to select the environment you have created and 
want to use with that notebook, from the top menu select the "Kernel" menu, 
then select "Change Kernel". 

EXAMPLE: If you have an 
environment named "newenv" that includes numpy and scipy that you want to use 
in your notebook, from the notebook's top Kernel menu select "Python [newenv]". 
The code in the notebook will run in that environment and will be able to 
import numpy and scipy functions.

.. On 4.1 this will be Python [conda env:test1-my_env] where test1 is the 
   project name and my_env is the env name.

Customizing
~~~~~~~~~~~

If you need a Python package that Anaconda Enterprise Notebooks doesn't
include by default, you can easily install additional packages into your
Anaconda Enterprise Notebooks environments.

TIP: You cannot install packages into the default Anaconda
environment. You must create your own environment, then install the new
packages into that environment.

Anaconda Enterprise Notebooks is built on Anaconda, so you can install 
additional Python packages using conda or pip, both of which 
are included with Anaconda. 

To install a Python package with conda, follow the above instructions to 
create and activate an environment. Then in your terminal, simply enter::

    conda install <packagename>
    
Specify the Python version you want when using conda to create the
environment. 

EXAMPLE::

    conda create -n mypy3 python=3 numpy scipy

This creates a conda environment named mypy3, running on Python 3 and 
containing NumPy and SciPy.

All subsequent packages added to this environment will be the python 3
compatible versions.

TIP: You can also install the package within your notebook without using 
a terminal app. From Jupyter Notebook's top menu select the conda file tab, 
click the environment you wish to use, search for the package you want, 
then click the Install button.

If you prefer to use conda or pip in a terminal window, you can do so 
in Anaconda Enterprise Notebooks with the terminal application, 
just like you would on your local system. 

You can also uninstall a package using this method with "conda 
remove <packagename>".

See `conda <http://conda.pydata.org/docs/>`_ for full documentation on 
using conda with a terminal application. 
