diff --git a/napari-workshops/installation.md b/napari-workshops/installation.md index d19c57f..8f3fba0 100644 --- a/napari-workshops/installation.md +++ b/napari-workshops/installation.md @@ -12,82 +12,103 @@ Make sure you review the instructions below and verify that they are still correct before using them in your workshop. ``` -## Installing Python using conda +## Installing Python using `conda` In this tutorial, we will install Python via miniforge, a distribution of Python based in the [conda package manager](https://docs.conda.io/en/latest/). + +````{important} If you already have anaconda, miniconda, or miniforge installed, those will work -as well and you can skip to the next section. - -1. In your web browser, navigate to the - [miniforge page](https://github.com/conda-forge/miniforge). -2. Scroll down to the "Miniforge3" header of the "Downloads" section. Click the - link to download the appropriate version for your operating system. *Note - that even if you have a new Apple computer with an M1 processor, you should - download the OS X x86_64 version.* - - Windows: `Miniforge3-Windows-x86_64` - - Mac with Intel processor: `Miniforge3-MacOSX-x86_64` - - Mac with M1 ("Apple silicon"): `Miniforge3-MacOSX-x86_64` - - Linux with an Intel processor: `Miniforge3-Linux-x86_64` -3. Once you have downloaded miniforge installer, run it to install Python. - - **Windows** - 1. Find the file you downloaded (`Miniforge3-Windows-x86_64.exe`) and - double click to execute it. Follow the instructions to complete the - installation. - 2. Once the installation has completed, you can verify it was correctly - installed by searching for the "miniforge prompt" in your Start menu. - - **Mac OS** - 1. Open your Terminal (you can search for it in spotlight - `cmd` + - `space`) - 2. Navigate to the folder you downloaded the installer to. For example, - if the file was downloaded to your Downloads folder, you would enter: - - ```bash - cd ~/Downloads - ``` - - 3. Execute the installer with the command below. You can use your arrow - keys to scroll up and down to read it/agree to it. - - ```bash - bash Miniforge3-MacOSX-x86_64.sh -b - ``` - - 4. To verify that your installation worked, close your Terminal window - and open a new one. You should see `(base)` to the left of your - prompt. - 5. Finally, initialize miniforge with the command below. This makes sure - that your terminal is set up correctly for your python installation. - - ```bash - conda init - ``` - - - **Linux** - 1. Open your terminal application - 2. Navigate to the folder you downloaded the installer to. For example, - if the file was downloaded to your Downloads folder, you would enter: - - ```bash - cd ~/Downloads - ``` - - 3. Execute the installer with the command below. You can use your arrow - keys to scroll up and down to read it/agree to it. - - ```bash - bash Miniforge3-Linux-x86_64.sh -b - ``` - - 4. To verify that your installation worked, close your Terminal window - and open a new one. You should see `(base)` to the left of your - prompt. - 5. Finally, initialize miniforge with the command below. This makes sure - that your terminal is set up correctly for your python installation. - - ```bash - conda init - ``` +as well. You can check using: + +```bash +conda info +``` + +However, we recommend you that the conda version is >23.10 and that you are using +[`conda-forge` channels](https://conda-forge.org/docs/user/introduction/). You can ensure this using: + +```bash +conda update conda +conda config --add channels conda-forge +``` + +Once you have that set, you can skip to [the next section](setting-up-your-napari-workshop-environment). +```` + +1. In your web browser, go to: +[https://conda-forge.org/download/](https://conda-forge.org/download/) +2. Click on the tile corresponding to your platform (e.g., Windows, macOS, or Linux) to download the installer. If you are unsure about your macOS or Linux architecture, open a command line terminal and run: + + ```bash + uname -m + ``` + + Alternately, you can also download the installer using the command line on macOS or Linux by running: + + ```bash + curl -L -O "https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-$(uname)-$(uname -m).sh" + ``` + +3. Once you have downloaded miniforge installer, run it to install conda. Note: you may need + admin permissions during the installation process. + + ### Windows + + 1. Find the file you downloaded (e.g. in your Downloads directory), it should look like `Miniforge3-Windows-x86_64.exe`. + 2. Double-click with the left mouse button to execute it. + 3. Follow the instructions to complete the installation. We recommend checking the options to "Create start menu shortcuts" and "Add Miniforge3 to my PATH environment variable". + 4. Once the installation has completed, you can verify it was correctly installed by searching for the “miniforge prompt” in your Start menu. + + ### macOS & Linux + + 1. Find the file you downloaded (e.g. in your Downloads directory), it should look like `Miniforge3-MacOSX-arm64.sh` or `Miniforge3-Linux-x86_64.sh`. + 2. Using the command line, navigate to the location of the installer. For example, if it's in the Downloads directory, you can run: + + ```bash + cd ~/Downloads + ``` + + 3. Run the installer by typing: + + ```bash + bash Miniforge3-$(uname)-$(uname -m).sh + ``` + + 4. The installer will walk you through a series of prompts to complete the installation. We recommend that you use the default installation location, but you can change it to a different location in your user directory if you prefer. + + 5. Once the installation finishes, the installer will ask: + `Do you wish to update your shell profile to automatically initialize conda?` + We recommend you answer `yes` to this question. This will add the necessary lines to your shell profile to ensure that `conda` is added to your PATH variable and properly initialized when you open a new shell. Note: For changes to take effect, you will need to close and re-open your current shell. + + 6. Once the installation has completed, you can verify it was correctly installed by opening a new command line. You should see `(base)` next to your command line prompt. Additionally, the following command: + + ``` + echo $CONDA_PREFIX + ``` + + should return the path to your `miniforge` installation, by default this is `~/miniforge3` (i.e., `miniforge3` in your home directory), so for example: + + + ```bash + /Users/username/miniforge3 + ``` + + or + + ```bash + /home/username/miniforge3 + ``` + + #### Manual initialization + + If you did not have the installer initialize your shell, you can manually initialize it. Note: the command depends on installation location of `miniforge`, by default this is `~/miniforge3`. Then, run: + + ```bash + ~/miniforge3/condabin/conda init + ``` + + Again, for changes to take effect, you will need to close and re-open your current shell. ## Setting up your environment 1. Open your terminal.