| Next revision | Previous revision |
| other:uvcdat:cdat_conda:miniforge_install [2025/09/17 16:48] – created jypeter | other:uvcdat:cdat_conda:miniforge_install [2025/10/06 16:54] (current) – [Why should you use Miniconda3 ?] Updated version, now that we use miniforge instead of miniconda jypeter |
|---|
| ====== JYP steps for installing Miniforge ====== | ====== JYP steps for installing Miniforge3 ====== |
| |
| <note warning> | <note warning> |
| Starting the Miniforge page, based on Miniconda | Starting the ''Miniforge3'' page, based on the ''[[other:uvcdat:cdat_conda:miniconda3_install|Miniconda3]]'' page |
| |
| LOTS of work to do!</note> | LOTS of testing 'n editing to do!</note> |
| |
| ===== Before installing Python on a shared Linux server ===== | ===== Before installing Python on a shared Linux server ===== |
| ==== Desperately seeking a specific package ==== | ==== Desperately seeking a specific package ==== |
| |
| Check if the Python package you are [[https://www.imdb.com/title/tt0089017/|desperately seeking]] is not already installed, before installing your own Python environment **on shared interactive Linux servers, or on batch computing clusters** !! | **Before** installing your own Python environment, check if the Python package you are [[https://www.imdb.com/title/tt0089017/|desperately seeking]] is not already available in an existing Python distribution on the **shared interactive Linux servers**, or the **batch computing clusters** you have access to !! |
| |
| * Ask other users who know the local environment | <wrap hi>Do not reinvent the wheel and waste shared disk space</wrap> |
| | |
| | * Ask other users who know the local environments |
| |
| * Read the servers/clusters Python-related documentation: [[https://wiki.lsce.ipsl.fr/pmip3/doku.php/other:python:starting|Python at LSCE by JYP]], [[https://intranet.lsce.ipsl.fr/informatique/index.php|LSCE]], [[https://documentations.ipsl.fr/spirit/spirit_clusters/python_modules.html|IPSL Mesocenter]], ... | * Read the servers/clusters Python-related documentation: [[https://wiki.lsce.ipsl.fr/pmip3/doku.php/other:python:starting|Python at LSCE by JYP]], [[https://intranet.lsce.ipsl.fr/informatique/index.php|LSCE]], [[https://documentations.ipsl.fr/spirit/spirit_clusters/python_modules.html|IPSL Mesocenter]], ... |
| * there is a //jupyter notebook server// connected to your Linux cluster (e.g. https://jupyter.lsce.ipsl.fr/) | * there is a //jupyter notebook server// connected to your Linux cluster (e.g. https://jupyter.lsce.ipsl.fr/) |
| * and an existing Python environment on this cluster providing all the packages you need | * and an existing Python environment on this cluster providing all the packages you need |
| but this Python environment is not directly available on the notebook server (in the listed //kernels//), you should follow the [[other:python:starting#using_a_non-standard_kernel|using a non-standard kernel]] instructions, rather than starting your own local notebook server (on this multi-user computer) | **but** this Python environment is not directly available on the notebook server (i.e. not listed in the //kernels// pull-down menu), you should follow the [[other:python:starting#using_a_non-standard_kernel|using a non-standard kernel]] instructions, rather than starting your own local notebook server (on this multi-user computer) |
| ===== Why should you use Miniconda3 ? ===== | ===== Why should you use Miniforge3 ? ===== |
| |
| FIXME: try using [[https://conda-forge.org/download/|Miniforge3]] instead of Miniconda3 ? | <note tip> |
| | * **You should use [[https://conda-forge.org/download/|Miniforge3]]** instead of ''Miniconda3'' or ''Anaconda3'' because it is not provided by the Anaconda company and is **completely free** |
| | * Check the [[https://www.anaconda.com/legal|Anaconda Legal]] page for more details |
| | * People with an existing ''Miconconda3'' based installation can have a look at the old [[other:uvcdat:cdat_conda:miniconda3_install|JYP steps for installing Miniconda3]] page |
| | </note> |
| |
| * **//Miniconda3// is a minimal/bootstrap Python distribution** that can be used for creating more complex Python distributions.\\ It will basically make a recent ''conda'' command/executable available on your computer, and you can then use this ''conda'' executable to select an existing distribution, or create new and independent Python distributions. | * **//Miniforge3// provides a free minimal/bootstrap Python distribution** that can be used for creating more complex Python distributions.\\ It will basically make a recent ''conda'' command/executable available on your computer, and you can then use this ''conda'' executable to create new and independent Python distributions, or select an existing distribution. |
| |
| * A **conda //environment//** is basically (the short name of the directory) where you install the Python that you will use (independently of //Miniconda3// itself). You have to ''activate'' this environment in order to use it\\ \\ A **Python //distribution//** is the collection of packages (and their dependencies) you have chosen to install together in a given environment. | * A **conda //environment//** is basically (the short name of the directory) where you install the Python that you will use (independently of //Miniforge3// itself). You have to ''activate'' this environment in order to use it\\ \\ A **Python //distribution//** is the collection of packages (and their dependencies) you have chosen to install together in a given environment. |
| * Example: initializing an environment named ''cdatm_py3'' (assuming it exists) in a //bash// shell <code>$ source /path_to_miniconda/etc/profile.d/conda.sh | * Example: initializing an environment named ''cdatm_py3'' (assuming it exists) in a //bash// shell <code>$ source /path_to_miniforge/etc/profile.d/conda.sh |
| |
| $ which conda | $ which conda |
| /path_to_miniconda/condabin/conda | /path_to_miniforge/condabin/conda |
| |
| $ conda env list | $ conda env list |
| [...] | [...] |
| cdatm_py3 /path_to_miniconda/envs/cdatm_py3 | cdatm_py3 /path_to_miniforge/envs/cdatm_py3 |
| some_other_env /path_to_miniconda/envs/some_other_env | some_other_env /path_to_miniforge/envs/some_other_env |
| |
| $ conda activate cdatm_py3 | $ conda activate cdatm_py3 |
| |
| (cdatm_py3) $ which python | (cdatm_py3) $ which python |
| /path_to_miniconda/envs/cdatm_py3/bin/python | /path_to_miniforge/envs/cdatm_py3/bin/python |
| </code> | </code> |
| * The //special// environment where //Miniconda3// itself is installed is called ''base'' (it also used to be called ''root''). Note that the ''python'' binary of the //special// ''base'' environment is not located in the same directory hierarchy as the ''python'' of the other environments (i.e. there is no ''envs/'' subdirectory<code>$ conda activate base | * The //special// environment where //Miniforge3// itself is installed is called ''base'' (it also used to be called ''root''). Note that the ''python'' binary of the //special// ''base'' environment is not located in the same directory hierarchy as the ''python'' of the other environments (i.e. there is no ''envs/'' subdirectory<code>$ conda activate base |
| |
| (base) $ which python | (base) $ which python |
| /path_to_miniconda/bin/python | /path_to_miniforge/bin/python |
| </code> | </code> |
| |
| * You **don't need to be (and you should not be !!) //root//** when you install //Miniconda3//. You just **need //enough// disk space** on a disk where you have write access | * You **don't need to be (and you should not be !!) //root//** when you install //Miniforge3//. You just **need //enough// disk space** on a disk where you have write access |
| * **WARNING**: by default, //Miniconda3// will install itself and subsequent Python environments in a sub-directory of your home directory (''~/miniconda3'' on Linux). **Do not use the default installation location**, if you want to avoid disk space related problems (//disk full//, //quota exceeded//, ...) during the inittial installation or later | * **WARNING**: by default, //Miniforge3// will install itself and subsequent Python environments in a sub-directory of your home directory (''~/miniforge3'' on Linux). **Do not use the default installation location**, if you want to avoid disk space related problems (//disk full//, //quota exceeded//, ...) during the initial installation or later |
| * **WARNING**: older versions of //Miniconda3// used a **hidden sub-directory** of the home directory of the person installing //Miniconda3// (''~/.conda'' on Linux) | * **WARNING**: older versions of //Miniforge3// used a **hidden sub-directory** of the home directory of the person installing //Miniforge3// (''~/.conda'' on Linux) |
| * Choose carefully where you will install //Miniconda3//, because the size of the installation directory will start at a few Gb and will keep on growing | * Choose carefully where you will install //Miniforge3//, because the size of the installation directory will start at a few Gb and will keep on growing |
| |
| * You //could// also start with the full //Anaconda// (instead of //Miniconda//) installer, that will install a much more complete python environment, ready for use.\\ **We choose not to use the full //Anaconda// installer** because: | |
| * It requires more disk space than //Miniconda3// during the initial installation, | |
| * All the //Anaconda// installer packages come from the ''default'' //channel// (or //repository//) provided by the [[https://anaconda.org/|conda repository]].\\ This is not very useful for us (and could even cause complex dependency problems later) because we will be mostly using (the same) packages provided by the [[https://conda-forge.org/feedstock-outputs/|conda-forge]] //channel//, **in order to avoid complex package dependency problems** | |
| |
| | ===== Downloading Miniforge3, and BASIC installation ===== |
| |
| ===== Downloading Miniconda3, and BASIC installation ===== | ==== Miniforge3 on a Windows computer ==== |
| |
| ==== Miniconda3 on a Windows computer ==== | Note: some of the steps below are adapted from the //Windows// sections of [[https://www.anaconda.com/docs/getting-started/miniconda/install|Installing Miniconda]] |
| |
| Some of the steps below are adapted from the [[https://docs.anaconda.com/free/miniconda/#quick-command-line-install|Windows section of "Quick command line install"]] to install a //pure Windows// version of Miniconda3 | === Downloading the Miniforge3 installer on Windows === |
| |
| === Downloading the Miniconda3 installer on Windows === | * The generic download link we use always points to the latest available version of the Windows installer |
| | * ''https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-Windows-x86_64.exe'' |
| | * Visit the [[https://github.com/conda-forge/miniforge/releases/latest|latest release page]] if you want to know the actual version number |
| | * October 2025: The ''Miniforge3 25.3.1-0'' installer is based on ''Python 3.12.11'' and ''Conda 25.3.1'' |
| |
| * We use a download link that always point to the [[https://docs.anaconda.com/free/miniconda/#latest-miniconda-installer-links|latest version of the Windows installer]] | * Find some temporary disk space on Windows to download the installer (71 Mb as of October 2025) |
| * https://repo.anaconda.com/miniconda/Miniconda3-latest-Windows-x86_64.exe | |
| * The installer is based on **Python 3.12.2 and Conda 24.3.0 as of April 2024** | |
| | |
| * Find some temporary disk space on Windows | |
| * e.g. ''C:\Scratch\your_login'' or whatever you use as a [[other:win10config#local_scratch_folder|local Scratch folder]] | * e.g. ''C:\Scratch\your_login'' or whatever you use as a [[other:win10config#local_scratch_folder|local Scratch folder]] |
| |
| * Open a //terminal//, where you can type the required installation commands | * Open a //terminal//, where you can type the required installation commands |
| * Windows //Powershell terminal//: ''Start'' => ''W'' => ''Windows PowerShell'' => ''Windows PowerShell'' | * Windows //Powershell terminal//: ''Start'' => ''W'' => ''Windows PowerShell'' => ''Windows PowerShell'' |
| * [[other:win10apps#windows_terminal|PowerShell in a Windows Terminal]] | * We recommend installing [[other:win10apps#windows_terminal|Windows Terminal]] and making it the default terminal for using Powershell |
| |
| * Use ''curl'' to download the latest installer (78 Mb as of April 2024): <code>PS C: cd C:\Scratch\your_login | * Use ''curl'' to download the latest installer (71 Mb as of October 2025): <code>PS C:\> cd C:\Scratch\your_login |
| PS C:\Scratch\your_login> curl https://repo.anaconda.com/miniconda/Miniconda3-latest-Windows-x86_64.exe -o miniconda.exe | |
| PS C:\Scratch\your_login> dir miniconda.exe | PS C:\Scratch\your_login> curl https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-Windows-x86_64.exe -o miniforge3.exe |
| | |
| | PS C:\Scratch\your_login> dir miniforge3.exe |
| [...] | [...] |
| -a---- 19/04/2024 11:18 81274240 miniconda.exe</code> | -a---- 17/09/2025 17:02 73476264 miniforge3.exe</code> |
| |
| === BASIC Miniconda3 installation on Windows === | === BASIC Miniforge3 installation on Windows === |
| |
| * **Determine the folder where you will install Miniconda3 and ALL your future Python environments** based on this version of Miniconda3\\ **We will later refer to this installation location as ''/path_to_miniconda3/''** in the [[#miniconda3_on_a_linux-like_computer|Linux sections]] below | * **Determine the folder where you will install Miniforge3 and ALL your future Python environments** based on this version of Miniforge3\\ **We will later refer to this installation location as ''/path_to_miniforge3/''** in the [[#miniforge3_on_a_linux-like_computer|Linux sections]] below |
| * Remember that **you will need a few Gb of available space** | * Remember that **you will need a few Gb of available disk space** |
| * You should **avoid installing Miniconda3 in your Windows //home// folder** (''C:\Users\your_login'' or [[other:win10config#local_home_folder|<some_disk_different_from_c>:\Users\<your_login>]]), if you want to be able to easily make backups or your //home// folder, without backing up thousands of files related to your Python environments... | * You should **avoid installing Miniforge3 in your Windows //home// folder** (''C:\Users\your_login'' or [[other:win10config#local_home_folder|<some_disk_different_from_c>:\Users\<your_login>]]), if you want to be able to easily create backups or your //home// folder, without backing up thousands of files related to your Python environments... |
| * We add some date or version information at the end of the folder name, in order to differentiate it from other (older of future) installations | * We add some date or version information at the end of the folder name, in order to differentiate it from other (older of future) installations |
| * Example installation folder: ''C:\Utils\miniconda3_2024-03'' (if we start installing in March 2024) | * Example installation folder: ''C:\Utils\miniforge3_2025-10'' (if we start installing in October 2025) |
| |
| * Launch the Miniconda3 installer with<code>PS C:\Scratch\your_login> .\miniconda.exe</code> | * Launch the Miniforge3 installer with<code>PS C:\Scratch\your_login> .\miniforge3.exe</code> |
| |
| * In the installer window: | * In the installer window: |
| * (Review and) accept the License Agreement | * (Review and) accept the //License Agreement// |
| * Choose to install for //Just Me// (the recommended default choice) | * Choose to install for //Just Me// (the recommended default choice) |
| * Specify the //Destination Folder// selected above, e.g. ''C:\Utils\miniconda3_2024-03'' | * Specify the //Destination Folder// selected above,\\ e.g. ''C:\Utils\miniforge3_2025-10'' |
| * Use the pre-selected //Advanced Installation Options//, i.e | * Use (only) the following //Advanced Installation Options// (probably pre-selected).\\ These options should have no side-effects on your system, or other existing Python installations on your system |
| * //Create start menu shortcutes// | * //Create shortcuts// |
| * //Register Miniconda3 as my default Python 3.12// <= Useful? | * This will add shortcuts to the Windows ''Start'' menu |
| * There is no need to bookmark the web pages suggested by the installer at the end, since this web page gives all the required information | * //Clear the package cache upon completion// |
| |
| * When the installer has finished running, you should have: | * When the installer has finished running, you should have: |
| * A new ''C:\Utils\miniconda3_2024-03'' folder | * A new ''C:\Utils\miniforge3_2025-10'' folder |
| * This folder size will be ~650 Mb and will keep on growing (up to several Gb) as you add more Python environments and packages | * This folder size will be ~300 Mb (as of October 2025) and will keep on growing (up to several Gb) as you add more Python environments and packages |
| * => **Be sure to have enough space on this disk!** | * => **Be sure to always have enough space on the installation disk!** |
| * Two new shortcuts in the Windows ''Start''=>''M''=>''Miniconda3'' menu: | * A new shortcut in the Windows ''Start'' menu: |
| * ''Anaconda Prompt'' | * ''Start''=>''M''=>''Miniforge3'' menu: |
| * ''Anaconda Powershell Prompt'' | * ''Miniforge Prompt'' shortcut |
| * **We will now use this //Anaconda Powershell// shortcut each time we need to use Miniconda3 or Python** | * We will now use this ''Miniforge Prompt'' shortcut each time we need to use a ''conda'' or ''python'' executable related to this installation of miniforge3 |
| * It is **highly recommended to [[other:win10apps#windows_terminal|install Windows Terminal and make it the default terminal application]]**, so that the ''conda'' prompts will open in a modern (and highly configurable) terminal | * We recommend to [[other:win10apps#windows_terminal|install Windows Terminal and make it the default terminal application]], so that the ''Miniforge'' prompts will open in a modern (and highly configurable) Windows terminal |
| |
| * Remove the installer<code>PS C:\Scratch\your_login> del .\miniconda.exe</code> | * Remove the installer<code>PS C:\Scratch\your_login> del miniforge3.exe</code> |
| |
| * Open an //Anaconda PowerShell Prompt//, and type a few commands to make sure that ''conda'' is working | * Open a //Miniforge Prompt//, and type a few commands to make sure that the newly installed ''conda'' and ''python'' run correctly\\ Opening a ''Miniforge prompt'' will automatically initialize the Python ''(base)'' environment installed with the Miniforge3 installer. |
| * ''Start''=>''M''=>''Miniconda3'' => ''Anaconda Powershell Prompt'' | * ''Start''=>''M''=>''Miniforge3'' => ''Miniforge Prompt'' |
| * <code>(base) PS C:\Users\your_login> conda env list | * <code>(base) C:\Users\your_login>where.exe conda |
| base * C:\Utils\miniconda3_2024-03 | C:\Utils\miniforge3_2025-10\Library\bin\conda.bat |
| | C:\Utils\miniforge3_2025-10\Scripts\conda.exe |
| | C:\Utils\miniforge3_2025-10\condabin\conda.bat |
| |
| (base) PS C:\Users\your_login> conda list | (base) C:\Users\your_login>conda --version |
| # packages in environment at C:\Utils\miniconda3_2024-03: | conda 25.3.1 |
| | |
| | (base) C:\Users\your_login>conda env list |
| | # conda environments: |
| | # |
| | base * C:\Utils\miniforge3_2025-10 |
| | |
| | (base) C:\Users\your_login>conda list |
| | # packages in environment at C:\Utils\miniforge3_2025-10: |
| | # |
| # Name Version Build Channel | # Name Version Build Channel |
| [...] | [...] |
| conda 24.3.0 py312haa95532_0 | conda 25.3.1 py312h2e8e312_1 conda-forge |
| | conda-libmamba-solver 25.3.0 pyhd8ed1ab_0 conda-forge |
| [...] | [...] |
| python 3.12.2 h1d929f7_0 | libmamba 2.1.1 h00a3e12_0 conda-forge |
| | libmambapy 2.1.1 py312h259b449_0 conda-forge |
| | [...] |
| | mamba 2.1.1 hbfb34a1_0 conda-forge |
| | [...] |
| | python 3.12.11 h3f84c4b_0_cpython conda-forge |
| [...] | [...] |
| |
| (base) PS C:\Users\your_login> conda deactivate | (base) C:\Users\your_login>python |
| | Python 3.12.11 | packaged by conda-forge | (main, Jun 4 2025, 14:29:09) [MSC v.1943 64 bit (AMD64)] on win32 |
| | Type "help", "copyright", "credits" or "license" for more information. |
| | >>> import sys, pprint |
| | >>> pprint.pprint(sys.path) |
| | ['', |
| | 'C:\\Utils\\miniforge3_2025-10\\python312.zip', |
| | 'C:\\Utils\\miniforge3_2025-10\\DLLs', |
| | 'C:\\Utils\\miniforge3_2025-10\\Lib', |
| | 'C:\\Utils\\miniforge3_2025-10', |
| | 'C:\\Utils\\miniforge3_2025-10\\Lib\\site-packages'] |
| | >>> ^Z</code> |
| |
| PS C:\Users\your_login> conda env list | * Check if ''conda-forge'' is the default and only channel that ''conda'' will use to update the newly installed ''base'' environment, and future environments |
| base C:\Utils\miniconda3_2024-03</code> | * The ''%%--%%get channels'' command should only mention ''%%'%%conda-forge%%'%%''<code>(base) C:\Users\jypeter>conda config --get channels |
| | --add channels 'conda-forge' # lowest priority</code> |
| | * **If you get something else**, you may have a ''.condarc'' configuration file left over from a previous ''conda'' installation. Depending on its content, you may have to remove or edit the ''.condarc'' file, or it may be OK to leave it unchanged |
| | * Example: you use a ''cmd'' terminal, and there is NO existing ''.condarc'' file<code>(base) C:\Users\your_login>more %HOMEPATH%\.condarc |
| | Impossible d’accéder au fichier C:\Users\your_login\.condarc</code> |
| | * Example: you use a Powershell terminal, and there is a configuration file. The configuration below is OK, because it only mentions the ''%%'%%conda-forge%%'%%'' channel we want<code>(base) PS C:\Users\your_login> more $HOME\.condarc |
| | channels: |
| | - conda-forge |
| | channel_priority: strict</code> |
| |
| * **Next**: be sure to <wrap hi>follow the steps in the [[other:uvcdat:cdat_conda:miniconda3_install#fine-tuning_conda_to_use_only_conda-forge|Fine-tuning conda to use (only) conda-forge]], and **all** the other Miniconda3 related instructions</wrap> | * **Next**: follow **all** the other Miniforge3 related instructions for the other Operating Systems |
| * ''conda'' commands will work the same way on all Operating Systems (Windows and Linux-like) | * ''conda'' **commands will work the same way on all Operating Systems** (Windows and Linux-like) |
| * The ''.condarc'' is located in your Windows //home// folder\\ => ''C:\Users\your_login\.condarc'' (or ''$HOME\.condarc'') | * If instructions mention the ''.condarc'' configuration file, it is located in your Windows //home// folder\\ => ''C:\Users\your_login\.condarc'' |
| | * Easily displaying the configuration file |
| | * ''cmd'': ''more %HOMEPATH%\.condarc'' |
| | * Powershell: ''more $HOME\.condarc'' |
| |
| ==== Miniconda3 on a Linux-like computer ==== | ==== Miniconda3 on a Linux-like computer ==== |
| * [[https://docs.conda.io/projects/conda-build/en/latest/resources/package-spec.html#package-match-specifications|conda Package match specifications]] | * [[https://docs.conda.io/projects/conda-build/en/latest/resources/package-spec.html#package-match-specifications|conda Package match specifications]] |
| * [[https://conda.io/projects/conda/en/latest/dev-guide/api/conda/models/match_spec/index.html#conda.models.match_spec.MatchSpec|Documentation in the MatchSpec class]] | * [[https://conda.io/projects/conda/en/latest/dev-guide/api/conda/models/match_spec/index.html#conda.models.match_spec.MatchSpec|Documentation in the MatchSpec class]] |
| ===== Uninstalling Miniconda3 ===== | ===== Uninstalling Miniforge3 ===== |
| |
| ==== Windows computer ==== | ==== Windows computer ==== |
| |
| Miniconda3 can be removed like a regular Windows application | Miniforge3 can be removed like a regular Windows application |
| |
| * Go to the //Apps & features// panel | * Go to the //Apps & features// panel |
| * ''Start'' => ''Settings'' => ''Apps'' => ''Apps & features'' | * ''Start'' => ''Settings'' => ''Apps'' => ''Apps & features'' |
| * Select ''Miniconda3 py3xxxxx'' | * Select ''Miniforge3 some_version_information'' |
| * Click on ''Uninstall'' and follow the instructions displayed by the uninstaller window | * Click on ''Uninstall'' and follow the instructions displayed by the //uninstaller// window |
| * This will remove: | * This will remove: |
| * The (very big) directory that you specified when you installed //Miniconda3// | * The (very big) directory that you specified when you installed //Miniforge3// |
| * The ''conda'' shortcuts from the ''Start Menu'' | * The ''Miniforge3'' shortcuts from the ''Start Menu'' |
| * This will **not** remove your local configuration file ''C:\Users\your_login\.condarc'' | * This will **not** remove your local configuration file ''C:\Users\your_login\.condarc'' |
| |
