mirror of
https://github.com/jupyterhub/the-littlest-jupyterhub.git
synced 2025-12-18 21:54:05 +08:00
215 lines
6.6 KiB
Markdown
215 lines
6.6 KiB
Markdown
(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.
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
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
|
|
```
|