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 recognize it and all project members have access to it.

This introduction to conda environments is specifically for AEN users. 
See `conda <http://conda.pydata.org/docs/>`_ for full conda documentation, 
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. To  
limit their read, write and/or execute permissions from the Workbench app, 
select the notebook name, then select Permissions from the resulting 
drop-down menu. 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. 

From that 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

To use your new environment with Jupyter Notebooks, open the notebook app 
and open a new notebook by clicking the NEW button. 
In the resulting drop-down menu, under Notebooks, the environment you just 
created appears. Select that environment to activate it.

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 "my_env" in a project named "test1" 
that includes NumPy and SciPy and want to use this environment in your 
notebook, select "Python [conda env:test1-my_env]" from the notebook's top 
Kernel menu. The notebook code will run in that environment and can import 
NumPy and SciPy functions.

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. 
