remote-sensing/notebooks/adding-python-libraries.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "fad43de4",
   "metadata": {},
   "source": [
    "# Adding custom python libraries <img align=\"right\" src=\"../resources/csiro_easi_logo.png\">\n",
    "It is possible to add additional python libraries to your notebook environment, but you first need to follow the steps below.\n",
    " \n",
    "This example creates a new environment called **myenv**. You should replace all instances of **myenv** with whatever name you would like to call your new environment."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8e8fb95b",
   "metadata": {},
   "source": [
    "### 1. Create new virtual environment\n",
    "First, **in a terminal** (File>New>Terminal), create a virtual environment\n",
    "```bash\n",
    "MYENV=myenv\n",
    "python3 -m venv ~/venvs/${MYENV}\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e491b605-ef63-4532-9b23-3a67ea3046e4",
   "metadata": {},
   "source": [
    "<div class=\"alert alert-info\">\n",
    "    <p><strong>NOTE: </strong>Make sure that you replace <code>myenv</code> every time with whatever name you would like for your new environment.</p>\n",
    "</div>"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8d4a13dc",
   "metadata": {},
   "source": [
    "### 2. Load default libraries\n",
    "In order to load all of the default python libraries that are installed in the default environment (e.g. including gdal, dask, boto, plotly, holoviews and many others), run the following command:\n",
    "\n",
    "```bash\n",
    "PYVERS=`python -c \"import sys; print('{0[0]}.{0[1]}'.format(sys.version_info))\"`\n",
    "\n",
    "realpath /env/lib/python${PYVERS}/site-packages > ~/venvs/${MYENV}/lib/python${PYVERS}/site-packages/base_venv.pth\n",
    "```\n",
    "\n",
    ">__NOTE:__ Replace `myenv` with whatever name you are using for your new environment."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8bd3e8da",
   "metadata": {},
   "source": [
    "### 3. Install new libraries\n",
    "Switch into the new venv if you haven't done so already in step 1\n",
    "```bash\n",
    "source ~/venvs/${MYENV}/bin/activate\n",
    "```\n",
    ">__NOTE:__ Replace `myenv` with whatever name you are using for your new environment."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "025f7e8f",
   "metadata": {},
   "source": [
    "You will now be able to nstall new libraries into your new environment, e.g. Below we install [geopy](https://geopy.readthedocs.io/en/stable/)\n",
    "\n",
    "```bash\n",
    "pip install geopy\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a1475b4e",
   "metadata": {},
   "source": [
    "### 4. Virtual Env in EASI Hub Jupyter (optional)\n",
    "\n",
    "You can then add the new environment as a kernel inside Jupyter by running the following line. \n",
    "\n",
    ">__NOTE:__ you ___MUST___ have your new environment activated (as shown above - `source ~/venvs/myenv/bin/activate`) before running the command below.\n",
    "> When activated, the environment name should be visible to the left of the command line, like below\n",
    "\n",
    "```bash\n",
    "(myenv) jovyan@jupyter-userid:~$\n",
    "```\n",
    "\n",
    "Then run:\n",
    "\n",
    "```sh\n",
    "python -m ipykernel install --user --name=\"My environment\"\n",
    "```\n",
    ">__NOTE:__ Replace `My environment` with a human-readable name for your new environment."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "2bf7e38b",
   "metadata": {},
   "source": [
    "After running this example above, refresh the browser and click on the words \"Python 3\" at the top right. This allows you to select a different Kernel, including your new **\"My environment\"** environment or whatever name you choose."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "528c49d5-8253-4278-9c0f-167b3dd60597",
   "metadata": {},
   "source": [
    "### 5. Return, review and clean up"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "2e128e23",
   "metadata": {},
   "source": [
    "---\n",
    "To disconnect from your new virtual environment and return to the default, use the following command in the terminal:\n",
    "```bash\n",
    "deactivate\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "fe6c55da-75c8-4b9c-b213-0af01d0e416a",
   "metadata": {},
   "source": [
    "---\n",
    "To list all available Jupyter kernels:\n",
    "```bash\n",
    "jupyter kernelspec list\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "749d9410-3011-4a48-a503-c01485bb202e",
   "metadata": {},
   "source": [
    "---\n",
    "To remove a kernel from Jupyter:\n",
    "```bash\n",
    "jupyter kernelspec uninstall unwanted-kernel\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d3d66bb5-035a-4ec0-b5e6-96ea131975f8",
   "metadata": {},
   "source": [
    "And then if you want to fully delete your custom python environment, simply delete it from the filesystem:\n",
    "```bash\n",
    "rm -r ~/venvs/${MYENV}\n",
    "```"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "87786ad4-fa3c-4a66-9b62-9a39b7c64506",
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "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.12.7"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}