getting-started/virutal-env.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Creating Python Virtual Environments with conda"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "- [Overview](#conda-virual-env-overview)\n",
    "- [Setting Up a Virtual Environment Using conda](#setting-up-a-virtual-environment-using-conda)\n",
    "- [Loading a conda Virtual Environment](#loading-a-conda-virtual-environment)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<a id=\"conda-virual-env-overview\"></a>\n",
    "## Overview\n",
    "\n",
    "A Python virtual environment is a named, isolated, working copy of Python that maintains its own files, directories, and paths so that you can work with specific versions of libraries or Python itself without affecting other Python projects.\n",
    "Virtual environments make it easy to cleanly separate projects and avoid problems with different dependencies and version requirements across components.\n",
    "The conda command-line interface (CLI) is the preferred interface for managing installations and virtual environments with the Anaconda Python distribution.\n",
    "The Jupyter Notebook service of the Iguazio Data Science Platform (\"the platform\") comes pre-deployed with conda.\n",
    "This tutorial explains how to use conda to create a Python virtual environment that will be available as a custom kernel in Jupyter Notebook.\n",
    "For general information about using conda to create virtual environments, see the [conda documentation](https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<a id=\"setting-up-a-virtual-environment-using-conda\"></a>\n",
    "## Setting Up a Virtual Environment Using conda\n",
    "\n",
    "Follow these steps from your Jupyter Notebook service to create a Python virtual environment using conda: \n",
    "\n",
    "1.  <a id=\"conda-virt-env-setup-step-create-terminal\"></a>Create a new terminal by selecting the **New Launcher** option (`+` icon) from the top action toolbar in the left sidebar, and then selecting **Terminal** from the main work area.<br>\n",
    "   The next steps should be executed from your new terminal, except where otherwise specified.\n",
    "\n",
    "\n",
    "2.  <a id=\"conda-virt-env-setup-step-create-env\"></a>Create a new Python virtual environment by running the following command.\n",
    "    Replace `<environment name>` with your preferred virtual-environment name:\n",
    "    ```sh\n",
    "    conda create -n <environment name> ipykernel\n",
    "    ```\n",
    "\n",
    "    <br>For example, the following command creates an environment named \"myenv\":<br>\n",
    "    ```sh\n",
    "    conda create -n myenv ipykernel\n",
    "    ```\n",
    "\n",
    "\n",
    "3. <a id=\"conda-virt-env-setup-step-install-packages\"></a>Install the desired Python packages by running the following command.\n",
    "   Replace `<environment name>` with the name of the environment that you created in the previous step and `<package>` with the name of your selected package, optionally followed by `=<version>`; you can specify multiple packages:\n",
    "   ```sh\n",
    "   conda install -n <environment name> <package> [<package> ...]\n",
    "   ```\n",
    "\n",
    "   <br>For example, the following command installs the SciPy, pandas version 0.25.0, and TensorFlow version 1.13.1 packages for a \"myenv\" environment:\n",
    "   ```sh\n",
    "   conda install -n myenv scipy pandas=0.25.0 tensorflow=1.13.1\n",
    "   ```\n",
    "\n",
    "\n",
    "4.  <a id=\"conda-virt-env-setup-step-export-env\"></a>Export your new virtual environment to an environment file in a platform data container by running the following command.\n",
    "    Replace `<container name>` with the name of a platform data container, `<directory path>` with an optional relative container-directories path, and `<environment name>` with the name of the environment that you created:\n",
    "    ```sh\n",
    "    conda env export -n <environment name> > /v3io/<container name>[/<directory path>]/<environment name>.yaml\n",
    "    ```\n",
    "\n",
    "    <br>It's recommended that you save the environment to a virtual-environments directory in your running-user home directory (**users/&lt;running user&gt;**).\n",
    "    For example, the following command creates a **users/&lt;running user&gt;/virutal_env/myenv.yaml** file:\n",
    "    ```sh\n",
    "    conda env export -n myenv > /v3io/users/$V3IO_USERNAME/virtual_env/myenv.yaml\n",
    "    ```\n",
    "    You can use the `User` data mount to the running-user directory to shorten this command (see [Platform Data Containers](collect-n-explore.ipynb/#platform-data-containers)):\n",
    "    ```sh\n",
    "    conda env -n myenv export > /User/virtual_env/myenv.yaml\n",
    "    ```\n",
    "\n",
    "\n",
    "5.  <a id=\"conda-virt-env-setup-step-refresh-ui\"></a>Refresh the JupyterLab UI to apply your changes.\n",
    "    After refreshing the UI, you should be able to see your new environment in the list of available kernels in Jupyter Notebook."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<a id=\"loading-a-conda-virtual-environment\"></a>\n",
    "## Loading a conda Virtual Environment\n",
    "\n",
    "If, for any reason, your conda environment variable is removed from Jupyter Notebook, you can easily deploy it again by using the YAML environment file that you exported in [Step 4](#conda-virt-env-setup-step-export-env):\n",
    "\n",
    "1.  Open a new Jupyter terminal\n",
    "\n",
    "2.  Run the following command to recreate the environment from the environment file.\n",
    "    Replace `<directory path>` and `<environment name>` to set the path to the enviornment file that you saved in the previous step:\n",
    "    ```sh\n",
    "    conda env create --file /v3io/<container name>[/<directory path>]/<environment name>.yaml\n",
    "    ```\n",
    "\n",
    "    <br>For example, the following command loads a **users/&lt;running user&gt;/virutal_env/myenv.yaml** environment file; the command uses the `User` running-user directory data mount to the running-user directory in the \"users\" container:\n",
    "\n",
    "    ```sh\n",
    "    conda env create --file  /User/virtual_env/myenv.yaml\n",
    "    ```"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.6.8"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}