diff --git a/docs/user/transitioning_from_defaults.md b/docs/user/transitioning_from_defaults.md index 515596e87c..d92b707775 100644 --- a/docs/user/transitioning_from_defaults.md +++ b/docs/user/transitioning_from_defaults.md @@ -1,91 +1,115 @@ -# Transitioning from Anaconda's default packages +# Transitioning from Anaconda's `defaults` channels -Users wishing to transition from Anaconda's default channel should do so with -care so as not to break their working environments. The first thing to realize +Users wishing to transition from Anaconda's `defaults` (i.e. those hosted under +https://repo.anaconda.com/pkgs) channels should do so with care so as not to +break their working environments. The first thing to realize is that in 2024 conda-forge is incompatible with the packages provided in -Anaconda's default channel. Often, the packages on conda-forge will require +`defaults`. Often, the packages on conda-forge will require newer versions of a particular package, or, may simply be organized in a different fashion. The only workflow we can support as a community is one where the conda-forge channel takes priority over all other channels. -If you were using `miniconda3` or `Anaconda3` and wish to move to use -conda-forge, we outline two workflow. The first allows you to try packages from +If you were using Miniconda or Anaconda Distribution and wish to move to use +conda-forge, we outline two workflows. The first allows you to try packages from conda-forge without uninstalling your previous installation, the second -involves uninstalling `miniconda3` or `Anaconda3`, and only using conda-forge -channels. +involves uninstalling Miniconda or Anaconda Distribution, and then installing +Miniforge. ## Trying conda-forge in an isolated environment -1. Create a conda-environment with very strict dependencies. The following - command will only use packages from conda-forge to install Python 3.11. You - may adjust the version of python to the one of your liking. +1. Create a conda environment with very few dependencies. The following + command will only use packages from `conda-forge` to install Python 3.11. You + may adjust the version of Python to the one of your liking: -```bash -conda create --name new_cf python=3.11 --channel conda-forge --override-channels -``` + ```bash + conda create --name conda-forge-env python=3.11 --channel conda-forge --override-channels + ``` -2. Activate your environment and add conda-forge with strict dependencies to - that particular environment. +2. Activate your environment and add `conda-forge` with strict priority to + that particular environment: -```bash - conda activate new_cf - conda config --env --add channels conda-forge - conda config --env --set channel_priority strict -``` + ```bash + conda activate conda-forge-env + conda config --env --add channels conda-forge + # optional: + # conda config --env --remove channels defaults + conda config --env --set channel_priority strict + ``` -3. Check the configuration of your conda environment. +3. Check the configuration of your conda environment: -```bash -conda config --show -``` + ```bash + conda config --show + ``` -Should list out that conda-forge is the top most channel in your list. + This should report that `conda-forge` is the top most channel in your list. -4. You are now in a position to use command likes +4. You are now in a position to use command like: -```bash -conda install my_desired_package_from_conda_forge -``` + ```bash + conda install my_desired_package_from_conda_forge + ``` -## Uninstalling Anaconda3 and installing miniforge3 +## Uninstalling Anaconda and installing Miniforge If you are ready to fully switch to conda-forge, we recommend uninstalling -Anaconda3 and installing miniforge3. The following steps are guidelines on how -to go about this, while backing up your work and your environments. +Anaconda / Miniconda and then installing [Miniforge](/download). The following steps +are guidelines on how to go about this, while backing up your work and your environments. 1. Clean your existing conda installation. This should remove unused files from - your anaconda folder and make for smaller sized backup. + your Anaconda / Miniconda installation and make for smaller sized backup. -``` -# The conda build purge command may fail if you don't have conda-build installed. -# this is expected -conda build purge -conda clean --all -``` + ```shell + # The conda build purge command may fail if you don't have conda-build installed. + # this is expected + conda build purge + conda clean --all + ``` 2. Create a zip archive of your conda installation. Use your favorite graphical tool - to right click on the miniconda3 installation folder - -3. On windows, following the system uninstalling installation prompts to - uninstall Anaconda prompts to uninstall Anaconda3. On linux and mac, delete - the folder called `anaconda3`, or `miniconda3`. + to right click on the Anaconda / Miniconda installation folder. Check if you have + created additional environments outside the installation root by running + `conda info --envs`. Back those up too, if necessary. + + - Alternatively, you can also export lockfiles for all your environments, if preferred: + ```shell + conda list --explicit --md5 --prefix /path/to/environment-name > environment-name.txt + ``` + Note these lockfiles will only include the conda packages. If you `pip install`ed packages + on top, those won't be captured. Check [`conda-lock`](https://conda.github.io/conda-lock/) + for those use cases. + + - Another useful file to create is the input `environment.yml` for each environment: + ```shell + conda env export --from-history --prefix --prefix /path/to/environment-name > environment-name.yml + ``` + This file won't capture the exact same state you had in your environment. Instead it + will tell `conda` what packages to look for and then find a solution that satisfies + the request. + +3. On Windows, use the uninstaller suggested by the system control panel. + On Linux and macOS, you can delete the folder called `anaconda3`, or `miniconda3` + (usually located in your home directory). 4. Find the file called `.condarc` in your home directory, and back it up somewhere safe. + Then, delete your old `.condarc` file. A new one specific to conda-forge will be + created when we install Miniforge. -5. Delete your old `.condarc` file. A new one specific to conda-forge will be - created when we install `miniforge3`. +5. On Linux and macOS, your shell profile (`~/.bashrc`) might contain initialization code + from the previous installation. Locate the block guarded by `# >>> conda initialize >>>` + comments and delete it. -6. Download and install the Miniforge3 installer that matches your platform from - https://github.com/conda-forge/miniforge +6. Download and install the Miniforge installer that matches your platform from + the [Miniforge download](/download) page. 7. Once installed, you should be able to use the `Miniforge3 Prompt` on - Windows, or the terminal on linux and mac, to run the command: + Windows, or the terminal on Linux and macOS, to run the command: -```bash -conda info -``` + ```shell + conda info + ``` -and notice that the conda-forge is the channel with the topmost priority. +Notice that the conda-forge is the channel with the topmost priority. You should now be in a position to use conda-forge packages. @@ -93,9 +117,9 @@ You should now be in a position to use conda-forge packages. Until roughly 2021, conda-forge held strong compatibility with Anaconda's default channel. However, due to the reasons outlined in XXXXXX, we decided to -ultimately move away from dependency on Anaconda's default packages. Over the -years, this has lead for more divergence between package versions, and names -between conda-forge and Anaconda's default channel. +ultimately move away from dependency on Anaconda's `defaults` packages. Over the +years, this has led for more divergence between package versions, and names +between conda-forge and Anaconda's `defaults` channel. In 2024, the workflow that has packages co-installed from Anaconda's channel and conda-forge is no longer supported. @@ -108,5 +132,5 @@ conda list --show-channel-urls All packages should specify that they have been installed from the conda-forge channel. In 2024, there still exist a few bugs where conda packages will -claim that they have been installed from PyPi even though they have been +claim that they have been installed from PyPI even though they have been installed from conda-forge.