Protected base installers

The protected base installer is a new Miniconda installer that protects your base conda environment from destructive changes. Many users inadvertently break their conda installation by installing all packages directly into the base environment, leading to dependency conflicts that are difficult to resolve without fully uninstalling and reinstalling. The protected base installer solves this by making base read-only and providing a default working environment for everyday use.

What’s different about this installer?

The protected base installer introduces two key changes:

• Protected base environment: The base environment is frozen and cannot be modified by conda install, pip install, or other package manager install commands. This prevents accidental breakage of your conda installation.
• Default working environment: Instead of activating base by default, the installer creates and activates a working environment, called python-<VERSION> (where <VERSION> is the installer’s default version of Python), for your day-to-day package installations.
• Different default install directory: Your install directory is miniconda3_pbe instead of miniconda3.

Anaconda strongly recommends creating a separate environment for each project to keep your dependencies isolated and your projects reproducible. For more information, see Why should I create a new environment.

Installing Miniconda with Protected Base Environment

If you do not have a current conda installation and want to try the protected base installer, download the installer for your platform below, then follow the standard Miniconda install instructions as a guide.

In Anaconda Navigator and Anaconda Desktop, your base environment is frozen and cannot be modified.

Choose your operating system and preferred installer type below:

Windows graphical

1. Navigate to anaconda.com/download, register with Anaconda, and then select Windows 64-bit Graphical Installer under Miniconda with Protected Base Environment in Beta Installers.
2. Continue with the Miniconda Windows graphical installer instructions, skipping the download step.

Windows CLI

Command Prompt

Open a Command Prompt window and run the following command:

curl https://repo.anaconda.com/miniconda/beta/Miniconda3-PBE-26.7.1.beta0-0-Windows-x86_64.exe --output .\Miniconda3-PBE-26.7.1.beta0-0-Windows-x86_64.exe

PowerShell

These commands work best with default PowerShell.

Open a PowerShell window and run the following command:

Invoke-WebRequest -Uri "https://repo.anaconda.com/miniconda/beta/Miniconda3-PBE-26.7.1.beta0-0-Windows-x86_64.exe" -OutFile ".\Miniconda3-PBE-26.7.1.beta0-0-Windows-x86_64.exe"

Continue with the Miniconda Windows shell installer instructions, skipping the download step.

macOS graphical

1. Navigate to anaconda.com/download, register with Anaconda, and then select 64-Bit (Apple silicon) Graphical Installer under Miniconda with Protected Base Environment in Beta Installers.
2. Continue with the Miniconda macOS graphical installer instructions, skipping the download step.

macOS CLI

1. Open a terminal and run the following command:

   curl -O https://repo.anaconda.com/miniconda/beta/Miniconda3-PBE-26.7.1.beta0-0-MacOSX-arm64.sh
   

2. Continue with the Miniconda macOS terminal installer instructions, skipping the download step.

Linux CLI

1. Open a terminal and run the following command, depending on your architecture:

   Linux x86

   curl -O https://repo.anaconda.com/miniconda/beta/Miniconda3-PBE-26.7.1.beta0-0-Linux-x86_64.sh
   

2. Continue with the Miniconda Linux installer instructions, skipping the download step.

Converting an existing installation

If you already have conda installed, you can convert your existing installation to use a protected base environment using the following command:

conda doctor --name base --fix

This converts your current installation without requiring a fresh install from the beta installer.

Managing your protected base environment

Because the base environment is protected, you cannot update conda or install plugins using the standard conda install command. Instead, use the conda self command to manage packages in the base environment:

Updating conda in your protected base environment

conda self update

Updating conda and all conda plugins in your protected base environment

conda self update --all

Installing a plugin into your protected base environment

This is only recommended for conda plugins or other packages that specifically modify conda. For more information on conda plugins, see Plugins in the official conda documentation.

Command

conda self install <PLUGIN>

Removing a plugin from your protected base environment

Command

conda self remove <PLUGIN>

More commands

For a full list of available commands, run:

conda self --help

For more information, see the conda-self documentation.

Override options

The following options bypass the protected base safeguards and are not recommended for regular use. Using them can lead to the same dependency conflicts and broken installations that the protected base feature prevents.

In rare cases where you must modify the base environment directly, the following override flags are available:

Override for conda

Use --override-frozen to bypass the frozen base protection when running conda commands:

conda install --override-frozen <PACKAGE>

Override for pip and other package managers

Use --break-system-packages to allow pip, uv, or other PyPA package managers to install into the protected base:

pip install --break-system-packages <PACKAGE>

Known limitations

• Some legacy workflows that depend on installing packages directly into base might require adjustment.
• Third-party tools that assume write access to the base environment might not work without using override flags.

Feedback and support

We want to hear about your experience with the protected base installer:

• General feedback: Submit feedback through the Community Forum or contact Anaconda Support.
• conda-self issues: Report bugs or feature requests for the conda self command at github.com/conda/conda-self.