This post mostly serves as an aide-mémoire, because I go through this install and set-up process often enough to remember it, but not often enough to precisely memorise every command. Hopefully you may find it useful too.

What are Python enviroments?

Python environments allows you to have isolated, separate installation of Python and modules. This is useful for many reasons: you may wish to avoid clashes between different versions of modules. Another use is having a bare-minimum environment that you can publish for others to reproduce, e.g. for verifying results in a paper that you’ve published (and help confirm your groundbreaking result isn’t just down a bug from having the latest upgrades blocked by some old package that’s been lurking on your computer for 18 months.)

Sounds good! How do I get virtual enviroments?

There are multiple different approaches, including the built-in venv, Conda and Anaconda, and others. I tend to lean towards Conda, partly because it’s a great solution for installing packages, and also deals with legacy Python 2 packages best.

So what’s the difference between Anaconda and Conda?

Anaconda is an installation of Conda that comes pre-loaded with a bunch of packages geared towards scientific computing. These are the usual ones you’ll have heard of: numpy, matplotlib, scipy, etc. It also comes with an IDE called Spyder, and Jupyter notebooks out of the box. This is great for beginners, but doesn’t give you as much control, and more importantly, given that we are trying to avoid package clashes, having pre-installed packages doesn’t help with that.

Therefore, I tend to want to just install Conda, the package manager, with no pre-installed packages, by using Miniconda.

So then what’s mambaforge?

We need to break this into two parts: Conda-forge is an online repository (or “channel”, in conda parlance) of Python packages. As a community run channel, it has much more software, and often has the more cutting edge versions, than the default Anaconda channel. It’s pretty much always a good idea to use the conda-forge version of a package if it exists, unless the package documentation explicitly says otherwise (some may want you to use Pip - see below). It’s very easy to set any Conda installation to use conda-forge channels by default; the website prominently displays the required commands. However, there also versions of Miniconda (such as Miniforge) that automatically have conda-forge set up as the default channel - therefore, it’s preferable to use Miniforge over Miniconda.

Meanwhile, mamba is a re-imagining of the conda package manager software. It works in exactly the same way (even down to the same commands), but it is a lot faster, and I find tends to do a better job resolving package dependencies. It’s very easy to install, you just install the mamba package into your environment with conda install mamba - but if you plan to use it in every environment (and I’m yet to encounter a reason not to use it), it’s handy to have it pre-installed - this is where Mambaforge comes in, as it is Miniforge but with mamba preinstalled.

Mambaforge it is - but how do I install it?

I’ll leave this to the miniforge/Mambaforge team themselves to explain, especially as it can be a bit complicated on Mac and especially on Windows. Remember to run conda init at the end of your installation in your shell.

Creating and using virtual enviroments

Whatever your flavour of conda, hopefully you now have it installed and initialised. So:

Activating an environment

Type conda activate to activate the base environment. (This is the only time you need to use conda instead of mamba - though this may be changing in a future update.)

Do not install any packages in your base environment! This tends to break things. Instead, let’s create a new environment:

Making a new environment

Specify a name for the enviroment, and a version of Python (if not, it just defaults to the latest). For example, to create an environment called “myenv” with Python 3.8, type mamba create -n myenv python=3.7. Note that environment names can’t have spaces in them.

Deleting an environment

Do ‘mamba env remove -n ENVNAME`. You’ll need to deactivate the environment first. Also, it goes without saying, but don’t try to remove your base environment. (If things have gone that badly that you feel you need to do this, probably best to just reinstall.)

Working with packages

This will create a new blank enviroment for you to play with. Don’t forget to activate it first with conda activate ENVNAME.

Install packages

Installing packages with mamba

Now that we are in your new environment, to install packages, you simply do mamba install <packages>, e.g. mamba install numpy matplotlib. If you want to specify a particular version or minimum requirement, you can do this: e.g. mamba install "numpy=X.X" "matplotlib>Y.Y".

Of course, if there’s a long list of packages to install, this would be a pain. If you’re attempting to reproduce someone elses environment, then hopefully they’ve provided you a YAML file with a list of the packages. In which case, it’s simply mamba env create --file envname.yml. To create a YAML file to export an environment, run mamba env export --name ENVNAME > envname.yml

Installing packages with pip

Occasionally a package may not be available through conda (this tends to be the case for smaller or self-published packages.) You can often install these with pip install <package>. Conda can deal with this, but it’s best to use a conda (and preferably conda-forge) version of a package if it is available. Also, try to install all the conda packages first, and do pip commands last, to minimise the risk of environment clashes.

You can install a list of packages with pip using pip install -r list.txt. To export a list of packages to a file, run pip freeze > list.txt.

See what packages are installed

Do mamba list to see what’s in the current environment, or mamba list -n <envname> to see what’s listed in another environment.

Removing packages

This can have a nasty habit of breaking dependencies, especially if involving pip packages, but if it really must be done, then run mamba remove <package>. It will also show what dependencies need to be removed. Pro tip: with Mamba, you can easily see package dependencies with a tool called repoquery: try mamba repoquery whoneeds numpy to see what requires Numpy to be installed, or mamba repoquery depends numpy to see what Numpy itself depends on.