conda-forge/miniforge

Miniforge

This repository holds the minimal installers for Conda and Mamba specific to conda-forge, with the following features pre-configured:

• Packages in the base environment are obtained from the conda-forge channel.
• The conda-forge 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) as well as the stability of this installer.

Goals

The goal of this installer is to provide you with an entry point to the conda and mamba commands. If these two commands execute correctly, then this installer has achieved its goal.

If you have issues with specific packages, please report them to the associated feedstock. You may find the feedstock associated with a package using our website

Usage

Miniforge provides installers for the commands conda and 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 "Miniforge Prompt". To be able to use these commands in other terminals, one needs to initialize conda for your shell by running in the Miniforge Prompt.

conda init

Note that one can also just add the C:\Users\myusername\miniforge3\condabin\ folder to the path environment variable manually 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

~/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

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 my_project)

conda create --name my_project jupyterlab numpy pandas
conda activate my_project
# Now you can start jupyter lab
jupyter lab

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

Latest installers with Python 3.13 (*) in the base environment:

(*) 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 or Ubuntu for 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.

(****) The Windows installer requires Windows 10 or later. However, we are unsure exactly what version of Windows 10. We need help from users to maintain the backlog of windows questions.

Install

Windows

We need help from activate users and willing maintainers!

Download and execute the Windows installer. Follow the prompts, taking note of the option to "Create start menu shortcuts". The most convenient and tested way to use the installed software (such as commands conda and mamba) is via the "Miniforge Prompt" installed to the start menu.

If you require conda to be accessible to other software, you may consider the option to "Add Miniforge3 to my PATH environment variable". The latter is not selected by default due to the potential of serious conflicts with other software. See https://github.com/conda-forge/miniforge/issues/520 and https://github.com/conda-forge/miniforge/issues/453.

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 and https://github.com/conda-forge/miniforge/issues/593. We recommend users install in a directory without any such characters in the name.

For non-interactive usage one can use the batch install option¹:

start /wait "" Miniforge3-Windows-x86_64.exe /InstallationType=JustMe /RegisterPython=0 /S /D=%UserProfile%\Miniforge3

Windows Subsystem for Linux (WSL)

The Windows Subsystem for Linux (WSL) lets developers use both Windows and Linux at the same time on a Windows machine. WSL users should make sure they are in a Linux terminal window (not Powershell) and use the Linux installer appropriate for the computer's architecture as described in the instructions in the next section.

Unix-like platforms (macOS, Linux, & WSL)

From a terminal window, download the installer appropriate for your computer's architecture using curl or wget or your favorite program.

For example:

curl -L -O "https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-$(uname)-$(uname -m).sh"

or

wget "https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-$(uname)-$(uname -m).sh"

Run the script with:

bash Miniforge3-$(uname)-$(uname -m).sh

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):

bash Miniforge3-$(uname)-$(uname -m).sh -b

In non-interactive installations, the conda initialization commands will not be run by default.

Note that Miniforge has been repacked by other package managers such as Homebrew(https://formulae.brew.sh/cask/miniforge). However this can lead to many incompatibilities that we do not test for. As such, we do not recommend using Homebrew to install Miniforge.

macOS (PKG installers)

PKG installers are available for macOS as of 2026. They are signed and notarized with NumFOCUS certificates. Download and execute the PKG installer for Apple Silicon. or Intel, and follow the steps on screen by pressing Continue.

By the 4th screen, you can choose a different installation path by clicking on "Change Install Location". Other options may be available behind the "Customise" button. Importantly, you can choose to have the installer perform conda initialization for your shell.

Once ready, click on Install. If everything went according to plan, the Summary page will report success.

For unattended installs, please use the SH installers mentioned in the section above.

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

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"

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"

This will download the appropriate installer for the present architecture with the filename Miniforge3.sh. Run the shell script with the command in batch mode with the -b flag:

bash Miniforge3.sh -b -p "${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:

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

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:

# 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.

2. Remove the folder and all subfolders where the base environment for Miniforge was installed:

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.

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"

Features

• Automatic build of constructor.
• Automatic upload of constructor results.
• Automatic testing of constructor.
• Integration with conda-forge's developer documentation.
• Integration with conda-forge's official site.

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:

• Centos 7
• Debian Bullseye (11)
• Debian Bookworm (12)
• Debian Trixie (13)
• Ubuntu 18.04 (LTS)
• Ubuntu 20.04 (LTS)
• Ubuntu 22.04 (LTS)
• Ubuntu 24.04 (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:

With Docker

# Configuration
export ARCH=aarch64
export DOCKERIMAGE=condaforge/linux-anvil-aarch64

bash build_miniforge.sh

Without Docker (Linux)

# Configuration
export TARGET_PLATFORM=linux-64

bash scripts/build.sh
bash scripts/test.sh

Be sure to delete the installation directory after build/test.sh has run. You will get installation errors if you run subsequent tests.

***** Run the installer *****
+ chmod +x build/Miniforge3-25.1.1-2-Linux-x86_64.sh
++ uname
+ [[ Linux == MINGW* ]]
+ [[ Miniforge3 == \M\i\n\i\f\o\r\g\e\3 ]]
+ sh build/Miniforge3-25.1.1-2-Linux-x86_64.sh -b -p /home/user001/miniforge
ERROR: File or directory already exists: '/home/user001/miniforge'
If you want to update an existing installation, use the -u option.

Without docker (Windows)

You must have Git Bash, or some other MINGW64 shell installed on Windows for this to run successfully.

export TARGET_PLATFORM=win-64

bash scripts/build.sh
bash scripts/test.sh

Support for older operating systems

Support for macOS 10.13-10.15

If you require support for macOS 10.13 through 10.15 you may download version 26.1.1-3 of miniforge available at https://github.com/conda-forge/miniforge/releases/tag/26.1.1-3

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 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 https://github.com/conda-forge/miniforge/releases/tag/24.3.0-0

FAQ

What's the difference between Mambaforge and Miniforge?

After the release of Miniforge 23.3.1 in August 2023, Miniforge and Mambaforge are essentially identical. The only difference is the name of the installer and subsequently the default installation path.

Before that release, Miniforge only shipped conda, while Mambaforge added mamba on top. Since Miniconda started shipping conda-libmamba-solver in July 2023, Miniforge followed suit and started shipping it too in August. At that point, since conda-libmamba-solver depends on libmambapy, the only difference between Miniforge and Mambaforge was the presence of the mamba Python package. To minimize surprises, we decided to add mamba to Miniforge too.

Should I choose one or another going forward at the risk of one of them getting deprecated?

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:

• Make a new pre-release on GitHub with name $CONDA_VERSION-$BUILD_NUMBER
• Wait until all artifacts are uploaded by CI
  • For each build, we upload 3 artifacts
    1. One installer with the version name
    2. One installer without the version name
    3. The SHA256
  • For OSX we also have one pkg installer for each architecture, with the 2 OSX names.
  • At the time of writing, the is a sum of 28 artifacts, and with the two sources, we expect a grand total of 30 artifacts.
• Mark the pre-release as a release

NOTE: using a pre-release is important to make sure the latest links work.

License

BSD 3-Clause

History

Relevant conversations:

• https://github.com/conda-forge/conda-forge.github.io/issues/871#issue-496677528
• https://github.com/conda-forge/conda-forge.github.io/pull/922

🚨 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 effort.

To help with this transition, the latest installers will:

• The installer will refuse to proceed every two weeks in October
• The installer will refuse to proceed every ten days in November
• The installer will refuse to proceed every five days in December
• The installer will refuse to proceed in 2025+

Miniforge-pypy3

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
Linux	x86_64 (amd64)	glibc >= 2.12	24.3.0-0
Linux	aarch64 (arm64)	glibc >= 2.17	24.9.2-0
Linux	aarch64 (arm64)	glibc >= 2.12	24.3.0-0
Linux	ppc64le (POWER8/9)	glibc >= 2.17	24.9.2-0
Linux	ppc64le (POWER8/9)	glibc >= 2.12	24.3.0-0
macOS	x86_64	macOS >= 10.13	24.9.2-0
macOS	x86_64	macOS >= 10.9	24.3.0-0
Windows	x86_64	Windows >= 7	24.9.2-0

🚨 Mambaforge (Deprecated as of July 2024) 🚨

Update for July 2024:

As of July 2024, Mambaforge is deprecated. We suggest users switch to Miniforge3 immediately. These installers will be retired from new releases after January 2025. To assist in the migration, we will be introducing rollowing brownouts to the latest Mambaforge installer. Installers up to version 24.5.0-1 will not have any brownouts. 24.5.0-1 will include a warning message. Installers 2024.5.0-2 and later will have the following brownout schedule:

• The installer will refuse to proceed every two weeks in October
• The installer will refuse to proceed every ten days in November
• The installer will refuse to proceed every five days in December
• The installer will refuse to proceed in 2025+

Previous information:

With the release of Miniforge3-23.3.1-0, that incorporated the changes in #277, the packages and 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 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

• Every two weeks in October
• Every ten days in November
• Every five days in December
• Never in 2025

You can still find the latest installers in the 24.9.2 release.

Footnotes

1. CLI parameter docs ↩