the-littlest-jupyterhub/docs/howto/user-env/user-environment.md

(howto/user-env/user-environment)=

# Install conda, pip or apt packages

`TLJH (The Littlest JupyterHub)`{.interpreted-text role="abbr"} starts
all users in the same [conda](https://conda.io/docs/) environment.
Packages / libraries installed in this environment are available to all
users on the JupyterHub. Users with [admin rights](#howto-admin-admin-users)
can install packages easily.

(howto/user-env/user-environment-pip)=

## Installing pip packages

[pip](https://pypi.org/project/pip/) is the recommended tool for
installing packages in Python from the [Python Packaging Index
(PyPI)](https://pypi.org/). PyPI has almost 145,000 packages in it right
now, so a lot of what you need is going to be there!

1.  Log in as an admin user and open a Terminal in your Jupyter
    Notebook.

    ![New Terminal button under New menu](../../images/notebook/new-terminal-button.png)

    If you already have a terminal open as an admin user, that should
    work too!

2.  Install a package!

    ```bash
    sudo -E pip install numpy
    ```

    This installs the `numpy` library from PyPI and makes it available
    to all users.

    :::{note}
    If you get an error message like `sudo: pip: command not found`,
    make sure you are not missing the `-E` parameter after `sudo`.
    :::

(howto/user-env/user-environment-conda)=

## Installing conda packages

Conda lets you install new languages (such as new versions of python,
node, R, etc) as well as packages in those languages. For lots of
scientific software, installing with conda is often simpler & easier
than installing with pip - especially if it links to C / Fortran code.

We recommend installing packages from
[conda-forge](https://conda-forge.org/), a community maintained
repository of conda packages.

1.  Log in as an admin user and open a Terminal in your Jupyter
    Notebook.

    ![New Terminal button under New menu](../../images/notebook/new-terminal-button.png)

    If you already have a terminal open as an admin user, that should
    work too!

2.  Install a package!

    ```bash
    sudo -E conda install -c conda-forge gdal
    ```

    This installs the `gdal` library from `conda-forge` and makes it
    available to all users. `gdal` is much harder to install with pip.

    :::{note}
    If you get an error message like `sudo: conda: command not found`,
    make sure you are not missing the `-E` parameter after `sudo`.
    :::

(howto/user-env/user-environment-apt)=

## Installing apt packages

[apt](https://help.ubuntu.com/lts/serverguide/apt.html.en) is the
official package manager for the [Ubuntu Linux
distribution](https://www.ubuntu.com/). You can install utilities (such
as `vim`, `sl`, `htop`, etc), servers (`postgres`, `mysql`, `nginx`,
etc) and a lot more languages than present in `conda` (`haskell`,
`prolog`, `INTERCAL`). Some third party software (such as
[RStudio](https://www.rstudio.com/products/rstudio/download/)) is
distributed as `.deb` files, which are the files `apt` uses to install
software.

You can search for packages with [Ubuntu Package
search](https://packages.ubuntu.com/) - make sure to look in the version
of Ubuntu you are using!

1.  Log in as an admin user and open a Terminal in your Jupyter
    Notebook.

    ![New Terminal button under New menu](../../images/notebook/new-terminal-button.png)

    If you already have a terminal open as an admin user, that should
    work too!

2.  Update list of packages available. This makes sure you get the
    latest version of the packages possible from the repositories.

    ```bash
    sudo apt update
    ```

3.  Install the packages you want.

    ```bash
    sudo apt install mysql-server git
    ```

    This installs (and starts) a [MySQL](https://www.mysql.com/)
    database server and `git`.

## User environment location

The user environment is a conda environment set up in `/opt/tljh/user`,
with a `python3` kernel as the default. It is readable by all users, but
writeable only by users who have root access. This makes it possible for
JupyterHub admins (who have root access with `sudo`) to install software
in the user environment easily.

## Accessing user environment outside JupyterHub

We add `/opt/tljh/user/bin` to the `$PATH` environment variable for all
JupyterHub users, so everything installed in the user environment is
available to them automatically. If you are using `ssh` to access your
server instead, you can get access to the same environment with:

```bash
export PATH=/opt/tljh/user/bin:${PATH}
```

Whenever you run any command now, the user environment will be searched
first before your system environment is. So if you run
`python3 <somefile>`, it\'ll use the `python3` installed in the user
environment (`/opt/tljh/user/bin/python3`) rather than the `python3`
installed in your system environment (`/usr/bin/python3`). This is
usually what you want!

To make this change \'stick\', you can add the line to the end of the
`.bashrc` file in your home directory.

When using `sudo`, the `$PATH` environment variable is usually reset, for
security reasons. This leads to error messages like:

```bash
sudo conda install -c conda-forge gdal
sudo: conda: command not found
```

The most common & portable way to fix this when using `ssh` is:

```bash
sudo PATH=${PATH} conda install -c conda-forge gdal
```

## Upgrade to a newer Python version

All new TLJH installs use miniconda 4.7.10, which comes with a Python
3.7 environment for the users. The previously TLJH installs came with
miniconda 4.5.4, which meant a Python 3.6 environment.

To upgrade the Python version of the user environment, one can:

- **Start fresh on a machine that doesn\'t have TLJH already
  installed.**

  See the [](#install-installing) section about how to install TLJH.

- **Upgrade Python manually.**

  Because upgrading Python for existing installs can break packages
  already installed under the old Python, upgrading your current TLJH
  installation, will NOT upgrade the Python version of the user
  environment, but you may do so manually.

  **Steps:**
  1.  Activate the user environment, if using ssh. If the terminal was
      started with JupyterHub, this step can be skipped:

      ```bash
      source /opt/tljh/user/bin/activate
      ```

  2.  Get the list of currently installed pip packages (so you can
      later install them under the new Python):

      ```bash
      pip freeze > pip_pkgs.txt
      ```

  3.  Update all conda installed packages in the environment:

      ```bash
      sudo PATH=${PATH} conda update --all
      ```

  4.  Update Python version:

      ```bash
      sudo PATH=${PATH} conda install python=3.7
      ```

  5.  Install the pip packages previously saved:

      ```bash
      pip install -r pip_pkgs.txt
      ```