From f811d9af5676e67bc71d19837694c5ae208e4513 Mon Sep 17 00:00:00 2001 From: paugier Date: Wed, 27 Nov 2024 14:02:45 +0100 Subject: [PATCH 1/3] README: format and regularize --- README.md | 112 ++++++++++++++++++++++++++++++++---------------------- 1 file changed, 67 insertions(+), 45 deletions(-) diff --git a/README.md b/README.md index 564ca385..0bab472c 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,5 @@ # Miniforge + [![Build miniforge](https://github.com/conda-forge/miniforge/actions/workflows/ci.yml/badge.svg)](https://github.com/conda-forge/miniforge/actions/workflows/ci.yml) [![GitHub downloads](https://img.shields.io/github/downloads/conda-forge/miniforge/total.svg)](https://tooomm.github.io/github-release-stats/?username=conda-forge&repository=miniforge) @@ -17,14 +18,14 @@ Miniforge installers are available here: https://github.com/conda-forge/miniforg Latest installers with Python 3.12 `(*)` in the base environment: -| OS | Architecture | Minimum Version | Download | -| --------|-------------------------------|------------------|-----------| -| Linux | x86_64 (amd64) | glibc >= 2.17 | `Miniforge3-Linux-x86_64` @ [latest](https://github.com/conda-forge/miniforge/releases/latest) | -| Linux | aarch64 (arm64) `(**)` | glibc >= 2.17 | `Miniforge3-Linux-aarch64` @ [latest](https://github.com/conda-forge/miniforge/releases/latest) | -| Linux | ppc64le (POWER8/9) | glibc >= 2.17 | `Miniforge3-Linux-ppc64le` @ [latest](https://github.com/conda-forge/miniforge/releases/latest) | -| macOS | x86_64 | macOS >= 10.13 | `Miniforge3-MacOSX-x86_64` @ [latest](https://github.com/conda-forge/miniforge/releases/latest) | -| macOS | arm64 (Apple Silicon) `(***)` | macOS >= 11.0 | `Miniforge3-MacOSX-arm64` @ [latest](https://github.com/conda-forge/miniforge/releases/latest) | -| Windows | x86_64 | Windows >= 7 | `Miniforge3-Windows-x86_64` @ [latest](https://github.com/conda-forge/miniforge/releases/latest) | +| OS | Architecture | Minimum Version | Download | +| ------- | ----------------------------- | --------------- | ------------------------------------------------------------------------------------------------ | +| Linux | x86_64 (amd64) | glibc >= 2.17 | `Miniforge3-Linux-x86_64` @ [latest](https://github.com/conda-forge/miniforge/releases/latest) | +| Linux | aarch64 (arm64) `(**)` | glibc >= 2.17 | `Miniforge3-Linux-aarch64` @ [latest](https://github.com/conda-forge/miniforge/releases/latest) | +| Linux | ppc64le (POWER8/9) | glibc >= 2.17 | `Miniforge3-Linux-ppc64le` @ [latest](https://github.com/conda-forge/miniforge/releases/latest) | +| macOS | x86_64 | macOS >= 10.13 | `Miniforge3-MacOSX-x86_64` @ [latest](https://github.com/conda-forge/miniforge/releases/latest) | +| macOS | arm64 (Apple Silicon) `(***)` | macOS >= 11.0 | `Miniforge3-MacOSX-arm64` @ [latest](https://github.com/conda-forge/miniforge/releases/latest) | +| Windows | x86_64 | Windows >= 7 | `Miniforge3-Windows-x86_64` @ [latest](https://github.com/conda-forge/miniforge/releases/latest) | `(*)` The Python version is specific only to the base environment. Conda can create new environments with different Python versions and implementations. @@ -40,7 +41,7 @@ The versions listed as "System: 32-bit" are not compatible with the installers o
🚨 PyPy support is deprecated (Deprecated as of August 2024) 🚨 - + TL;DR: We are planning to remove PyPy from conda-forge feedstock recipes in a few weeks (and thus to stop building new releases of packages for PyPy), unless there is substantial enough interest to justify the continued maintenance @@ -59,17 +60,17 @@ Latest installers with PyPy 3.9 in the base environment are listed below. However, the latest installers will cease to work and will stop being made available in 2025. You should therefore pin to 24.7.0 if you require PyPy3. -| OS | Architecture | Minimum Version | Miniforge Version | -| --------|--------------------|------------------|-------------------| -| Linux | x86_64 (amd64) | glibc >= 2.17 | [24.9.2-0](https://github.com/conda-forge/miniforge/releases/tag/24.9.2-0) | -| Linux | x86_64 (amd64) | glibc >= 2.12 | [24.3.0-0](https://github.com/conda-forge/miniforge/releases/tag/24.3.0-0) | -| Linux | aarch64 (arm64) | glibc >= 2.17 | [24.9.2-0](https://github.com/conda-forge/miniforge/releases/tag/24.9.2-0) | -| Linux | aarch64 (arm64) | glibc >= 2.12 | [24.3.0-0](https://github.com/conda-forge/miniforge/releases/tag/24.3.0-0) | -| Linux | ppc64le (POWER8/9) | glibc >= 2.17 | [24.9.2-0](https://github.com/conda-forge/miniforge/releases/tag/24.9.2-0) | -| Linux | ppc64le (POWER8/9) | glibc >= 2.12 | [24.3.0-0](https://github.com/conda-forge/miniforge/releases/tag/24.3.0-0) | -| macOS | x86_64 | macOS >= 10.13 | [24.9.2-0](https://github.com/conda-forge/miniforge/releases/tag/24.9.2-0) | -| macOS | x86_64 | macOS >= 10.9 | [24.3.0-0](https://github.com/conda-forge/miniforge/releases/tag/24.3.0-0) | -| Windows | x86_64 | Windows >= 7 | [24.9.2-0](https://github.com/conda-forge/miniforge/releases/tag/24.9.2-0) | +| OS | Architecture | Minimum Version | Miniforge Version | +| ------- | ------------------ | --------------- | -------------------------------------------------------------------------- | +| Linux | x86_64 (amd64) | glibc >= 2.17 | [24.9.2-0](https://github.com/conda-forge/miniforge/releases/tag/24.9.2-0) | +| Linux | x86_64 (amd64) | glibc >= 2.12 | [24.3.0-0](https://github.com/conda-forge/miniforge/releases/tag/24.3.0-0) | +| Linux | aarch64 (arm64) | glibc >= 2.17 | [24.9.2-0](https://github.com/conda-forge/miniforge/releases/tag/24.9.2-0) | +| Linux | aarch64 (arm64) | glibc >= 2.12 | [24.3.0-0](https://github.com/conda-forge/miniforge/releases/tag/24.3.0-0) | +| Linux | ppc64le (POWER8/9) | glibc >= 2.17 | [24.9.2-0](https://github.com/conda-forge/miniforge/releases/tag/24.9.2-0) | +| Linux | ppc64le (POWER8/9) | glibc >= 2.12 | [24.3.0-0](https://github.com/conda-forge/miniforge/releases/tag/24.3.0-0) | +| macOS | x86_64 | macOS >= 10.13 | [24.9.2-0](https://github.com/conda-forge/miniforge/releases/tag/24.9.2-0) | +| macOS | x86_64 | macOS >= 10.9 | [24.3.0-0](https://github.com/conda-forge/miniforge/releases/tag/24.3.0-0) | +| Windows | x86_64 | Windows >= 7 | [24.9.2-0](https://github.com/conda-forge/miniforge/releases/tag/24.9.2-0) |
@@ -100,7 +101,7 @@ configuration of `Mambaforge` and `Miniforge3` are now **identical**. The only difference between the two is the name of the installer and, subsequently, the default installation directory. -We recommend switching to `Miniforge3` immediately. These installers will be +We recommend switching to `Miniforge3` immediately. These installers will be retired in January 2025. To assist in the migration to Miniforge3 for CI users, we've stopped the latest Mambaforge (24.5+) installer from proceeding with following schedule @@ -120,13 +121,17 @@ You can still find the latest installers in the [24.9.2 release](https://github. Download the installer using curl or wget or your favorite program and run the script. For eg: - curl -L -O "https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-$(uname)-$(uname -m).sh" - bash Miniforge3-$(uname)-$(uname -m).sh +```sh +curl -L -O "https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-$(uname)-$(uname -m).sh" +bash Miniforge3-$(uname)-$(uname -m).sh +``` or - wget "https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-$(uname)-$(uname -m).sh" - bash Miniforge3-$(uname)-$(uname -m).sh +```sh +wget "https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-$(uname)-$(uname -m).sh" +bash Miniforge3-$(uname)-$(uname -m).sh +``` #### Uninstallation @@ -135,7 +140,7 @@ You will typically want to remove: 1. Any modifications to your shell rc files that were made by Miniforge: -```bash +```sh # Use this first command to see what rc files will be updated conda init --reverse --dry-run # Use this next command to take action on the rc files listed above @@ -147,7 +152,7 @@ conda init --reverse 2. Remove the folder and all subfolders where the base environment for Miniforge was installed: -```bash +```sh CONDA_BASE_ENVIRONMENT=$(conda info --base) echo The next command will delete all files in ${CONDA_BASE_ENVIRONMENT} # Warning, the rm command below is irreversible! @@ -158,7 +163,7 @@ rm -rf ${CONDA_BASE_ENVIRONMENT} 3. Any global conda configuration files that are left behind. -```bash +```sh echo ${HOME}/.condarc will be removed if it exists rm -f "${HOME}/.condarc" echo ${HOME}/.conda and underlying files will be removed if they exist. @@ -182,15 +187,21 @@ We recommend users install in a directory without any such characters in the nam For non-interactive usage one can use the batch install option: - bash Miniforge3-Linux-x86_64.sh -b # or similar for other installers for unix platforms +```sh +bash Miniforge3-Linux-x86_64.sh -b # or similar for other installers for unix platforms +``` Look at the extra options by running the following: - bash Miniforge3-Linux-x86_64.sh -h +```sh +bash Miniforge3-Linux-x86_64.sh -h +``` or if you are on windows, run: - start /wait "" Miniforge3-Windows-x86_64.exe /InstallationType=JustMe /RegisterPython=0 /S /D=%UserProfile%\Miniforge3 +``` +start /wait "" Miniforge3-Windows-x86_64.exe /InstallationType=JustMe /RegisterPython=0 /S /D=%UserProfile%\Miniforge3 +``` ### Downloading the installer as part of a CI pipeline @@ -199,38 +210,48 @@ more automated fashion, you may wish to a command similar to For Linux, any architecture, use the following command - wget -O Miniforge3.sh "https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-$(uname)-$(uname -m).sh" - +```sh +wget -O Miniforge3.sh "https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-$(uname)-$(uname -m).sh" +``` For macOS, any architecture, use the following command - curl -fsSLo Miniforge3.sh "https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-MacOSX-$(uname -m).sh" +```sh +curl -fsSLo Miniforge3.sh "https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-MacOSX-$(uname -m).sh" +``` This will download the appropriate installer for the present architecture with -the filename ``Miniforge3.sh``. Run the shell script with the command in batch +the filename `Miniforge3.sh`. Run the shell script with the command in batch mode with the `-b` flash: - bash Miniforge3.sh -b -p "${HOME}/conda" +```sh +bash Miniforge3.sh -b -p "${HOME}/conda" +``` `-p` is prefix option. A directory wil be created on `"${HOME}/conda"`. Then you should create the path to conda and activate conda. Run this command: - source "${HOME}/conda/etc/profile.d/conda.sh" - # For mamba support also run the following command - source "${HOME}/conda/etc/profile.d/mamba.sh" +```sh +source "${HOME}/conda/etc/profile.d/conda.sh" +# For mamba support also run the following command +source "${HOME}/conda/etc/profile.d/mamba.sh" +``` Finally, you can run the command to activate the base environment - conda activate - +```sh +conda activate +``` ### Homebrew On macOS, you can install miniforge with [Homebrew](https://brew.sh/) by running - brew install miniforge +```sh +brew install miniforge +``` ## Usage @@ -272,7 +293,7 @@ After construction on the CI, the installer is tested against a range of distrib Installers are built and uploaded via the CI but if you want to construct your own Miniforge installer, here is how: -```bash +```sh # Configuration export ARCH=aarch64 export DOCKERIMAGE=condaforge/linux-anvil-aarch64 @@ -283,14 +304,15 @@ bash build_miniforge.sh ## Support for older operating systems ### Support for macOS 10.9-10.12 + If you require support for macOS 10.9 through 10.12 you may download version -24.3.0-0 of miniforge available at +24.3.0-0 of miniforge available at https://github.com/conda-forge/miniforge/releases/tag/24.3.0-0 ### Support for glibc 2.12-2.16 If you require support for glibc 2.12 through 2.16 you may download version -24.3.0-0 of miniforge available at +24.3.0-0 of miniforge available at https://github.com/conda-forge/miniforge/releases/tag/24.3.0-0 ## FAQ From bfeba232e2d3e4cde53e0e47f2d92a90ed43b01a Mon Sep 17 00:00:00 2001 From: paugier Date: Wed, 27 Nov 2024 14:58:36 +0100 Subject: [PATCH 2/3] Reorganize README for better readability --- README.md | 196 +++++++++++++++++++++++++++++------------------------- 1 file changed, 106 insertions(+), 90 deletions(-) diff --git a/README.md b/README.md index 0bab472c..8744b913 100644 --- a/README.md +++ b/README.md @@ -8,35 +8,7 @@ This repository holds the minimal installers for [Conda](https://conda.io/) and * Packages in the base environment are obtained from the [conda-forge channel](https://anaconda.org/conda-forge). * The [conda-forge](https://conda-forge.org/) channel is set as the default (and only) channel. -We put an emphasis on supporting various CPU architectures (x86_64, ppc64le, and aarch64 including Apple Silicon). Optional support for PyPy in place of standard Python interpreter (aka "CPython") is provided in the installers with `-pypy3-` in their filename. - -## Download - -Miniforge installers are available here: https://github.com/conda-forge/miniforge/releases - -### Miniforge3 - -Latest installers with Python 3.12 `(*)` in the base environment: - -| OS | Architecture | Minimum Version | Download | -| ------- | ----------------------------- | --------------- | ------------------------------------------------------------------------------------------------ | -| Linux | x86_64 (amd64) | glibc >= 2.17 | `Miniforge3-Linux-x86_64` @ [latest](https://github.com/conda-forge/miniforge/releases/latest) | -| Linux | aarch64 (arm64) `(**)` | glibc >= 2.17 | `Miniforge3-Linux-aarch64` @ [latest](https://github.com/conda-forge/miniforge/releases/latest) | -| Linux | ppc64le (POWER8/9) | glibc >= 2.17 | `Miniforge3-Linux-ppc64le` @ [latest](https://github.com/conda-forge/miniforge/releases/latest) | -| macOS | x86_64 | macOS >= 10.13 | `Miniforge3-MacOSX-x86_64` @ [latest](https://github.com/conda-forge/miniforge/releases/latest) | -| macOS | arm64 (Apple Silicon) `(***)` | macOS >= 11.0 | `Miniforge3-MacOSX-arm64` @ [latest](https://github.com/conda-forge/miniforge/releases/latest) | -| Windows | x86_64 | Windows >= 7 | `Miniforge3-Windows-x86_64` @ [latest](https://github.com/conda-forge/miniforge/releases/latest) | - -`(*)` The Python version is specific only to the base environment. Conda can create new environments with different Python versions and implementations. - -`(**)` For Raspberry PI that include a 64 bit processor, you must also use -a 64-bit operating system such as -[Raspberry Pi OS 64-bit](https://www.raspberrypi.com/software/operating-systems/#raspberry-pi-os-64-bit) -or -[Ubuntu for Raspberry PI](https://ubuntu.com/raspberry-pi). -The versions listed as "System: 32-bit" are not compatible with the installers on this website. - -`(***)` Apple silicon builds are experimental and haven't had testing like the other platforms. +We put an emphasis on supporting various CPU architectures (x86_64, ppc64le, and aarch64 including Apple Silicon).
@@ -114,96 +86,114 @@ You can still find the latest installers in the [24.9.2 release](https://github.
-## Install -### Unix-like platforms (macOS & Linux) +## Usage -Download the installer using curl or wget or your favorite program and run the script. -For eg: +If Miniforge is on the system path (default on macOS and Linux), its versions of the +[`conda`](https://conda.io/projects/conda/en/latest/user-guide/getting-started.html#managing-environments) and +[`mamba`](https://mamba.readthedocs.io/en/latest/user_guide/mamba.html#mamba-user-guide) programs can be used +at any command prompt. The most notable difference is that the default channel for packages will be conda-forge. -```sh -curl -L -O "https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-$(uname)-$(uname -m).sh" -bash Miniforge3-$(uname)-$(uname -m).sh -``` -or +## Requirements and installers -```sh -wget "https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-$(uname)-$(uname -m).sh" -bash Miniforge3-$(uname)-$(uname -m).sh -``` +Latest installers with Python 3.12 `(*)` in the base environment: -#### Uninstallation +| OS | Architecture | Minimum Version | File | +| ------- | ----------------------------- | --------------- | ------------------------------- | +| Linux | x86_64 (amd64) | glibc >= 2.17 | `Miniforge3-Linux-x86_64.sh` | +| Linux | aarch64 (arm64) `(**)` | glibc >= 2.17 | `Miniforge3-Linux-aarch64.sh` | +| Linux | ppc64le (POWER8/9) | glibc >= 2.17 | `Miniforge3-Linux-ppc64le.sh` | +| macOS | x86_64 | macOS >= 10.13 | `Miniforge3-MacOSX-x86_64.sh` | +| macOS | arm64 (Apple Silicon) `(***)` | macOS >= 11.0 | `Miniforge3-MacOSX-arm64.sh` | +| Windows | x86_64 | Windows >= 7 | `Miniforge3-Windows-x86_64.exe` | -Uninstalling Miniforge means removing the files that were created during the installation process. -You will typically want to remove: +`(*)` The Python version is specific only to the base environment. Conda can create new environments with different Python versions and implementations. -1. Any modifications to your shell rc files that were made by Miniforge: +`(**)` For Raspberry PI that include a 64 bit processor, you must also use +a 64-bit operating system such as +[Raspberry Pi OS 64-bit](https://www.raspberrypi.com/software/operating-systems/#raspberry-pi-os-64-bit) +or +[Ubuntu for Raspberry PI](https://ubuntu.com/raspberry-pi). +The versions listed as "System: 32-bit" are not compatible with the installers on this website. -```sh -# Use this first command to see what rc files will be updated -conda init --reverse --dry-run -# Use this next command to take action on the rc files listed above -conda init --reverse -# Temporarily IGNORE the shell message -# 'For changes to take effect, close and re-open your current shell.', -# and CLOSE THE SHELL ONLY AFTER the 3rd step below is completed. -``` +`(***)` Apple silicon builds are experimental and haven't had testing like the other platforms. -2. Remove the folder and all subfolders where the base environment for Miniforge was installed: + +## Install + +On all platforms, the installation should be finalized with commands like ```sh -CONDA_BASE_ENVIRONMENT=$(conda info --base) -echo The next command will delete all files in ${CONDA_BASE_ENVIRONMENT} -# Warning, the rm command below is irreversible! -# check the output of the echo command above -# To make sure you are deleting the correct directory -rm -rf ${CONDA_BASE_ENVIRONMENT} +conda init --all ``` -3. Any global conda configuration files that are left behind. +(see `conda init -h`) and potentially also ```sh -echo ${HOME}/.condarc will be removed if it exists -rm -f "${HOME}/.condarc" -echo ${HOME}/.conda and underlying files will be removed if they exist. -rm -fr ${HOME}/.conda +conda config --set auto_activate_base false ``` ### Windows -Download and execute the Windows installer. Follow the prompts, taking note of the options to +Download and execute [the Windows installer](https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-Windows-x86_64.exe). +Follow the prompts, taking note of the options to "Create start menu shortcuts" and "Add Miniforge3 to my PATH environment variable". The latter is not selected by default due to potential conflicts with other software. Without Miniforge3 on the path, the most convenient way to use the installed software (such as commands `conda` and `mamba`) will be via the "Miniforge Prompt" installed to the start menu. +If desired, the +`C:\Users\myusername\miniforge3\condabin` folder may be added to the path environment variable +[manually](https://learn.microsoft.com/en-us/previous-versions/office/developer/sharepoint-2010/ee537574(v=office.14)#to-add-a-path-to-the-path-environment-variable) +after installation so the software may be used more conveniently from any command prompt with limited chance of software conflicts. + There are known issues with the usage of special characters and spaces in the installation location, see for example https://github.com/conda-forge/miniforge/issues/484. We recommend users install in a directory without any such characters in the name. -### Non-interactive install - For non-interactive usage one can use the batch install option: ```sh -bash Miniforge3-Linux-x86_64.sh -b # or similar for other installers for unix platforms +start /wait "" Miniforge3-Windows-x86_64.exe /InstallationType=JustMe /RegisterPython=0 /S /D=%UserProfile%\Miniforge3 ``` -Look at the extra options by running the following: +### Unix-like platforms (macOS & Linux) + +Download the installer using curl or wget or your favorite program. For eg: ```sh -bash Miniforge3-Linux-x86_64.sh -h +curl -L -O "https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-$(uname)-$(uname -m).sh" ``` -or if you are on windows, run: +or +```sh +wget "https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-$(uname)-$(uname -m).sh" ``` -start /wait "" Miniforge3-Windows-x86_64.exe /InstallationType=JustMe /RegisterPython=0 /S /D=%UserProfile%\Miniforge3 + +Run the script with: + +```sh +bash Miniforge3-$(uname)-$(uname -m).sh ``` -### Downloading the installer as part of a CI pipeline +or for non-interactive install (call with `-h` to list the extra options): + +```sh +bash Miniforge3-$(uname)-$(uname -m).sh -b +``` + +### macOS with Homebrew + +On macOS, you can install miniforge with [Homebrew](https://brew.sh/) by running + +```sh +brew install miniforge +``` + +### As part of a CI pipeline If you wish to download the appropriate installer through the command line in a more automated fashion, you may wish to a command similar to @@ -245,27 +235,46 @@ Finally, you can run the command to activate the base environment conda activate ``` -### Homebrew -On macOS, you can install miniforge with [Homebrew](https://brew.sh/) by running +## Uninstall + +### Unix-like platforms (macOS & Linux) + +Uninstalling Miniforge means removing the files that were created during the installation process. +You will typically want to remove: + +1. Any modifications to your shell rc files that were made by Miniforge: ```sh -brew install miniforge +# Use this first command to see what rc files will be updated +conda init --reverse --dry-run +# Use this next command to take action on the rc files listed above +conda init --reverse +# Temporarily IGNORE the shell message +# 'For changes to take effect, close and re-open your current shell.', +# and CLOSE THE SHELL ONLY AFTER the 3rd step below is completed. ``` -## Usage +2. Remove the folder and all subfolders where the base environment for Miniforge was installed: -If Miniforge is on the system path (default on macOS and Linux), its versions of the -[`conda`](https://conda.io/projects/conda/en/latest/user-guide/getting-started.html#managing-environments) and -[`mamba`](https://mamba.readthedocs.io/en/latest/user_guide/mamba.html#mamba-user-guide) programs can be used -at any command prompt. The most notable difference is that the default channel for packages will be conda-forge. +```sh +CONDA_BASE_ENVIRONMENT=$(conda info --base) +echo The next command will delete all files in ${CONDA_BASE_ENVIRONMENT} +# Warning, the rm command below is irreversible! +# check the output of the echo command above +# To make sure you are deleting the correct directory +rm -rf ${CONDA_BASE_ENVIRONMENT} +``` + +3. Any global conda configuration files that are left behind. + +```sh +echo ${HOME}/.condarc will be removed if it exists +rm -f "${HOME}/.condarc" +echo ${HOME}/.conda and underlying files will be removed if they exist. +rm -fr ${HOME}/.conda +``` -On Windows, Miniforge is not added to the system path by default. In this case, `conda`/`mamba` cannot be used from -ordinary command prompts without the full path of the executables, e.g. `C:\Users\myusername\miniforge3\condabin\conda`. -Instead, it is recommended to use the Miniforge Prompt, available from the Start menu. If desired, the -`C:\Users\myusername\miniforge3\condabin` folder may be added to the path environment variable -[manually](https://learn.microsoft.com/en-us/previous-versions/office/developer/sharepoint-2010/ee537574(v=office.14)#to-add-a-path-to-the-path-environment-variable) -after installation so the software may be used more conveniently from any command prompt with limited chance of software conflicts. ## Features @@ -276,6 +285,7 @@ after installation so the software may be used more conveniently from any comman - [ ] Integration with conda-forge's official site. - [ ] Upstream to Anaconda ? + ## Testing After construction on the CI, the installer is tested against a range of distribution that match the installer architecture (`$ARCH`). For example when architecture is `aarch64`, the constructed installer is tested against: @@ -289,6 +299,7 @@ After construction on the CI, the installer is tested against a range of distrib - Ubuntu 22.04 ([LTS](https://ubuntu.com/about/release-cycle)) - Ubuntu 24.04 (Latest release -- also happens to be LTS) + ## Building a Miniforge Installer Installers are built and uploaded via the CI but if you want to construct your own Miniforge installer, here is how: @@ -301,6 +312,7 @@ export DOCKERIMAGE=condaforge/linux-anvil-aarch64 bash build_miniforge.sh ``` + ## Support for older operating systems ### Support for macOS 10.9-10.12 @@ -315,6 +327,7 @@ If you require support for glibc 2.12 through 2.16 you may download version 24.3.0-0 of miniforge available at https://github.com/conda-forge/miniforge/releases/tag/24.3.0-0 + ## FAQ ### What's the difference between Mambaforge and Miniforge? @@ -336,6 +349,7 @@ As of June 2024, Mambaforge is deprecated and will be retired in January 2025. We recommend users switch to Miniforge3 immediately. For more details, please see the note above. + ## Release To release a new version of Miniforge: @@ -351,10 +365,12 @@ To release a new version of Miniforge: NOTE: using a pre-release is important to make sure the latest links work. + ## License [BSD 3-Clause](./LICENSE) + ## History Relevant conversations: From e7201d3388dcd8d4d08ba7383afb2896d688d3ed Mon Sep 17 00:00:00 2001 From: paugier Date: Thu, 19 Dec 2024 12:12:20 +0100 Subject: [PATCH 3/3] Take into account @hmaarrfk's suggestions --- README.md | 88 ++++++++++++++++++++++++++++++++++++------------------- 1 file changed, 58 insertions(+), 30 deletions(-) diff --git a/README.md b/README.md index 8744b913..485827a6 100644 --- a/README.md +++ b/README.md @@ -89,11 +89,57 @@ You can still find the latest installers in the [24.9.2 release](https://github. ## Usage -If Miniforge is on the system path (default on macOS and Linux), its versions of the -[`conda`](https://conda.io/projects/conda/en/latest/user-guide/getting-started.html#managing-environments) and -[`mamba`](https://mamba.readthedocs.io/en/latest/user_guide/mamba.html#mamba-user-guide) programs can be used -at any command prompt. The most notable difference is that the default channel for packages will be conda-forge. +Miniforge provides installers for the commands [`conda`](https://conda.io/) and +[`mamba`](https://github.com/mamba-org/mamba). Once the installer for your OS +and architecture has been executed, you should be able to use these commands in +a terminal. +### conda/mamba usable in any terminals + +However, with the default choices of the Windows installer, these commands are +only available in the "Anaconda Prompt". To be able to use these commands in +other terminals, one needs to initialize conda for your shell by running in +the Anaconda Prompt + +```sh +conda init +``` + +Note that one can also just add the `C:\Users\myusername\miniforge3\condabin` folder +to the path environment variable +[manually](https://learn.microsoft.com/en-us/previous-versions/office/developer/sharepoint-2010/ee537574(v=office.14)#to-add-a-path-to-the-path-environment-variable) +so `conda` and `mamba` may be used more conveniently from any command prompt with limited +chance of software conflicts. + +The same situation arises on Unix if you use the non-interactive install. +Initialization can be done by calling conda with its full path, with something like + +```sh +~/miniforge3/bin/conda init +``` + +### Automatic activation of environments + +By default, once conda has been initialized for your shell, the `base` environment is +activated so that the command `python` corresponds to the base Python provided by +Miniforge and `conda install` installs packages in the `base` environment. This can +be convenient for but it is cleaner to deactivate this automatic activation with + +```sh +conda config --set auto_activate_base false +``` + +and use `conda` or `mamba` to create and activate other environments, with for example +(to create an environment called `main`) + +```sh +conda create --name main jupyterlab numpy pandas +conda activate main +``` + +Finally, it is also possible to add to your shell configuration file +(typically `~/.bashrc` or `~/.zshrc` on Unix; +on Windows, edit with `notepad $PROFILE`) the activation command. ## Requirements and installers @@ -119,21 +165,8 @@ The versions listed as "System: 32-bit" are not compatible with the installers o `(***)` Apple silicon builds are experimental and haven't had testing like the other platforms. - ## Install -On all platforms, the installation should be finalized with commands like - -```sh -conda init --all -``` - -(see `conda init -h`) and potentially also - -```sh -conda config --set auto_activate_base false -``` - ### Windows Download and execute [the Windows installer](https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-Windows-x86_64.exe). @@ -143,11 +176,6 @@ not selected by default due to potential conflicts with other software. Without path, the most convenient way to use the installed software (such as commands `conda` and `mamba`) will be via the "Miniforge Prompt" installed to the start menu. -If desired, the -`C:\Users\myusername\miniforge3\condabin` folder may be added to the path environment variable -[manually](https://learn.microsoft.com/en-us/previous-versions/office/developer/sharepoint-2010/ee537574(v=office.14)#to-add-a-path-to-the-path-environment-variable) -after installation so the software may be used more conveniently from any command prompt with limited chance of software conflicts. - There are known issues with the usage of special characters and spaces in the installation location, see for example https://github.com/conda-forge/miniforge/issues/484. @@ -179,19 +207,19 @@ Run the script with: bash Miniforge3-$(uname)-$(uname -m).sh ``` -or for non-interactive install (call with `-h` to list the extra options): +The interactive installation will prompt you to initialize conda with your shell. +This is typically with recommended workflow. + +For non-interactive install (for example on a CI), the following command can be used +(call with `-h` to list the extra options): ```sh bash Miniforge3-$(uname)-$(uname -m).sh -b ``` -### macOS with Homebrew - -On macOS, you can install miniforge with [Homebrew](https://brew.sh/) by running +In non-interactive installations, the conda initialization commands will not be run by default. -```sh -brew install miniforge -``` +Note that on macOS, Miniforge can also be installed with [Homebrew](https://brew.sh/). ### As part of a CI pipeline @@ -218,7 +246,7 @@ mode with the `-b` flash: bash Miniforge3.sh -b -p "${HOME}/conda" ``` -`-p` is prefix option. A directory wil be created on `"${HOME}/conda"`. +`-p` is prefix option. A directory will be created on `"${HOME}/conda"`. Then you should create the path to conda and activate conda. Run this command: