====== Installing Miniconda and Jupyter ======

This guide explains how to install **Miniconda** and **JupyterLab** on Windows, macOS, and Linux.

Miniconda is a minimal Python distribution containing Python, the ''conda'' package/environment manager, and a small set of basic packages. Jupyter is **not** included by default, so we will install it into a separate conda environment.

===== 1. Download Miniconda =====

The links below use Anaconda's ''latest'' aliases. This means that they should continue to point to the newest available Miniconda installer without requiring this tutorial to be updated for every release.

^ Operating system ^ Architecture ^ Installer ^
| Windows 10/11 | 64-bit Intel/AMD (x86-64) | [[https://repo.anaconda.com/miniconda/Miniconda3-latest-Windows-x86_64.exe|Download Miniconda for Windows]] |
| macOS | Apple Silicon (M1/M2/M3/M4/M5, ARM64) | [[https://repo.anaconda.com/miniconda/Miniconda3-latest-MacOSX-arm64.pkg|Download Miniconda for Apple Silicon Mac]] |
| macOS | Intel (x86-64, older Macs) | [[https://repo.anaconda.com/miniconda/Miniconda3-latest-MacOSX-x86_64.pkg|Download Miniconda for Intel Mac]] |
| Linux | 64-bit Intel/AMD (x86-64) | [[https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh|Download Miniconda for Linux x86-64]] |
| Linux | ARM64 / AArch64 | [[https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-aarch64.sh|Download Miniconda for Linux ARM64]] |

All available installers can also be found here:

[[https://repo.anaconda.com/miniconda/|Official Miniconda installer directory]]

**Important:** Intel Macs are now a legacy platform for Anaconda/Miniconda. The Intel installer remains available, but new Intel macOS builds are no longer produced. Most Macs sold since late 2020 use Apple Silicon.

===== 2. Windows =====

==== Install Miniconda ====

  - Download the **Windows x86-64** installer from the link above.
  - Double-click the downloaded ''.exe'' file.
  - Select **Just Me** when asked who should receive the installation.
  - Keep the default installation directory unless you have a reason to change it.
  - On the **Advanced Installation Options** screen:
    * keep **Create shortcuts** enabled;
    * **do not enable** //Add Miniconda3 to my PATH environment variable//;
    * keeping //Register Miniconda3 as my default Python// enabled is normally fine on a fresh computer.
  - Finish the installation.

==== Verify the installation ====

Open the Windows Start menu and search for **Anaconda Prompt**.

You should see ''(base)'' at the beginning of the prompt.

Run:

<code>
conda --version
python --version
</code>

If both commands print version numbers, Miniconda is installed correctly.

==== Optional: enable conda in PowerShell ====

If you want to use normal PowerShell instead of Anaconda Prompt, run this once from Anaconda Prompt:

<code>
conda init powershell
</code>

Then close and reopen PowerShell.

===== 3. macOS =====

==== Check which Mac you have ====

Most Macs sold since late 2020 use Apple Silicon.

You can check the processor in **Apple menu -> About This Mac**, or open Terminal and run:

<code bash>
uname -m
</code>

Possible results:

  * ''arm64'' -> Apple Silicon -> use the **MacOSX-arm64** installer.
  * ''x86_64'' -> Intel Mac -> use the **MacOSX-x86_64** installer.

==== Install Miniconda ====

  - Download the appropriate ''.pkg'' installer from the table above.
  - Open it and follow the installation wizard.
  - When installation has finished, close and reopen Terminal.

Verify the installation:

<code bash>
conda --version
python --version
</code>

If ''conda'' is not found, initialize it manually. A standard user installation is usually located in ''~/miniconda3'':

<code bash>
~/miniconda3/bin/conda init zsh
source ~/.zshrc
</code>

===== 4. Linux =====

==== Check the CPU architecture ====

Open a terminal and run:

<code bash>
uname -m
</code>

Usually you will see one of these:

  * ''x86_64'' -> standard Intel/AMD PC -> use **Linux-x86_64**.
  * ''aarch64'' or ''arm64'' -> ARM64 machine -> use **Linux-aarch64**.

==== Install Miniconda ====

Download the appropriate ''.sh'' installer from the table above. It will normally be saved in ''~/Downloads''.

For a normal Intel/AMD Linux computer:

<code bash>
cd ~/Downloads
bash Miniconda3-latest-Linux-x86_64.sh
</code>

For an ARM64 Linux computer:

<code bash>
cd ~/Downloads
bash Miniconda3-latest-Linux-aarch64.sh
</code>

During installation:

  - press **Enter** to read the license;
  - type ''yes'' to accept it;
  - press **Enter** to accept the default installation location;
  - answer ''yes'' when asked whether conda should initialize your shell.

After installation, close and reopen the terminal.

Alternatively, refresh the current terminal:

For Bash:

<code bash>
source ~/.bashrc
</code>

For Zsh:

<code bash>
source ~/.zshrc
</code>

Verify the installation:

<code bash>
conda --version
python --version
</code>

===== 5. Create a Jupyter environment =====

The following steps are the same on **Windows, macOS, and Linux**.

**Note:** It is good practice not to install course packages directly into the ''base'' environment. Instead, create a separate environment for Jupyter and the packages used in the course.

Create an environment named ''jupyter'' containing Python 3.13, JupyterLab, and the Python kernel:

<code>
conda create -n jupyter -c conda-forge --override-channels python=3.13 jupyterlab ipykernel
</code>

When conda asks whether to continue, type:

<code>
y
</code>

Activate the environment:

<code>
conda activate jupyter
</code>

Your terminal prompt should now begin with something similar to:

<code>
(jupyter)
</code>

===== 6. Start JupyterLab =====

Activate the environment if it is not already active:

<code>
conda activate jupyter
</code>

Navigate to the directory in which you want to work.

For example, on macOS/Linux:

<code bash>
cd ~/Documents
</code>

On Windows:

<code>
cd %USERPROFILE%\Documents
</code>

Start JupyterLab:

<code>
jupyter lab
</code>

JupyterLab should open automatically in your web browser.

<note>
Do not close the terminal window while JupyterLab is running. The Jupyter server runs in this terminal.
</note>

===== 7. Test the installation =====

In JupyterLab:

  - click **File -> New -> Notebook** or select the **Python** notebook launcher;
  - create a new cell;
  - enter:

<code python>
print("Jupyter is working!")

import sys
print(sys.version)
print(sys.executable)
</code>

Run the cell with **Shift + Enter**.

If the output is displayed without an error, the installation is working.

===== 8. Stop JupyterLab =====

Return to the terminal in which JupyterLab is running and press:

<code>
Ctrl+C
</code>

If asked whether you want to shut down the server, confirm with ''y''.

===== 9. Using Jupyter later =====

Every time you want to use this environment:

<code>
conda activate jupyter
jupyter lab
</code>

To leave the environment:

<code>
conda deactivate
</code>

===== 10. Installing additional Python packages =====

Activate the environment first:

<code>
conda activate jupyter
</code>

For example, to install NumPy, pandas, SciPy, and Matplotlib from conda-forge:

<code>
conda install -c conda-forge --override-channels numpy pandas scipy matplotlib
</code>

For packages that are not available through conda, use ''pip'' only **after activating the correct conda environment**:

<code>
python -m pip install PACKAGE_NAME
</code>

===== 11. Useful conda commands =====

^ Command ^ Meaning ^
| ''conda env list'' | List all conda environments |
| ''conda activate jupyter'' | Activate the Jupyter environment |
| ''conda deactivate'' | Leave the current environment |
| ''conda list'' | List packages installed in the active environment |
| ''conda remove -n jupyter --all'' | Completely delete the Jupyter environment |

===== Troubleshooting =====

==== ''conda: command not found'' ====

First close and reopen the terminal.

On macOS with Zsh:

<code bash>
~/miniconda3/bin/conda init zsh
source ~/.zshrc
</code>

On Linux with Bash:

<code bash>
~/miniconda3/bin/conda init bash
source ~/.bashrc
</code>

On Windows, open **Anaconda Prompt** from the Start menu instead of a normal Command Prompt.

==== Jupyter opens in the wrong environment ====

Check that the ''jupyter'' environment is active before starting JupyterLab:

<code>
conda activate jupyter
jupyter lab
</code>

You can check which Python executable is currently being used with:

<code>
python -c "import sys; print(sys.executable)"
</code>

===== Official documentation =====

  * [[https://www.anaconda.com/docs/getting-started/miniconda/install|Miniconda installation documentation]]
  * [[https://repo.anaconda.com/miniconda/|Official Miniconda installer archive]]
  * [[https://jupyter.org/install|Project Jupyter installation documentation]]
  * [[https://docs.conda.io/|Conda documentation]]