---
file_format: mystnb
kernelspec:
  name: python3
  display_name: python3
---


# Install instructions

We generally recommend creating a Python environment to isolate any code from other dependencies. This can be done using either `uv` or `conda`. `uv` is a fast Python package installer and resolver, written in Rust, and can be used as a modern alternative to `conda` for environment management. 

## Mac OS X / Linux

### Using `uv`

To create a Python environment using `uv` in a Mac OS X or Linux environment, first ensure `uv` is installed (e.g., `pip install uv`). Then run:

```{code-cell} ipython3
---
tags: [skip-execution]
---
uv venv islp
```

To run Python code in this environment, you must activate it:

```{code-cell} ipython3
---
tags: [skip-execution]
---
source islp/bin/activate
```

### Using `conda` (Alternative)

To create a Python conda environment in a Mac OS X or Linux environment run:

```{code-cell} ipython3
---
tags: [skip-execution]
---
conda create --name islp python
```

ISLP needs Python 3.11 or later; current conda should already provide it.
If not, replace `python` with a version such as `python=3.12`.
To run python
code in this environment, you must activate it:

```{code-cell} ipython3
---
tags: [skip-execution]
---
conda activate islp
```

## Windows

### Using `uv`

On Windows, you can create a Python environment called `islp` using `uv`. First, ensure `uv` is installed (e.g., `pip install uv`). Then, from a PowerShell terminal, run:

```{code-cell} ipython3
---
tags: [skip-execution]
---
uv venv islp
islp\Scripts\activate
```

### Using `conda` (Alternative)

On windows, create a `Python` environment called `islp` in the Anaconda app. This can be done by selecting `Environments` on the left hand side of the app's screen. After creating the environment, open a terminal within that environment by clicking on the "Play" button.

# Installing `uv` and `ISLP`

Having completed the steps above, we use `pip` to install `uv` and then `uv` to install `ISLP`:

```{code-cell} ipython3
---
tags: [skip-execution]
---
pip install uv
uv pip install ISLP
```

## Frozen environment

```{attention}

Python packages change frequently. The labs here are built
with  {{ ISLP_lab_link }}. Visit the lab git repo for specific instructions
to install the frozen environment.
```

## Torch requirements

The `ISLP` labs use `torch` and various related packages for the lab
on deep learning. Most of the requirements are included in the requirements for `ISLP` though the labs
also use `torchinfo` and `torchvision`. These will be installed by the `requirements.txt` above.

```{attention}
Because
`torch` and related libraries change frequently, you will note that we
have pinned the versions at specific versions that were used to make
current verisons of the labs.
```

## Jupyter

```{attention}
If using the Anaconda App, `jupyter` can be installed with a GUI. Use
the GUI install instead of the `pip` install below.
```

### Mac OS X

```{attention}

If you are using the Anaconda GUI, it is recommended that you install JupyterLab through the GUI
and skip the step below. Installing both through the GUI and `pip` may result in conflicts and
a broken JupyterLab.

If you have installed JupyterLab in your environment via the GUI, the above call `pip install ISLP` may be made within
any running notebook within that environment.
```

If JupyterLab is not already installed, run the following after having activated your `islp` environment:

```{code-cell} ipython3
---
tags: [skip-execution]
---
uv pip install jupyterlab
```

### Windows

Either use `pip install jupyterlab` or install JupyterLab from the
`Home` tab. Ensure that the environment is your `islp`
environment. This information appears near the top left in the
Anaconda `Home` page.

# Google Colab

The notebooks for the labs can be run in [Google
Colab](https://colab.research.google.com) with a few caveats:

- Labs that use files in the filesystem will require one to mount your
  Google Drive. See Google's [help](https://colab.research.google.com/notebooks/io.ipynb).

- The packages will have to be reinstalled each time a new runtime is started.
For most labs, inserting `pip install uv && uv pip install ISLP` at the top of the notebook will suffice, though Colab will ask you to restart after installation.