Skip to content

Take over an existing conda environment

by Tim Hopper
Scientific Python

You just joined a team or lab that uses conda. Someone handed you an environment.yml and told you to conda activate. This tutorial walks through the day-to-day operations: creating an environment from a file, exploring what’s installed, adding packages, handling the conda+pip boundary, and exporting a reproducible environment for teammates.

Prerequisites

Install Miniforge following the Miniforge installation instructions.

Important

Use Miniforge, not Miniconda or Anaconda. Miniforge defaults to the conda-forge channel, which is community-maintained and freely licensed. Miniconda and Anaconda default to the defaults channel, which requires a paid license for commercial use at organizations with more than 200 employees. See Is Conda Actually Free? for the full licensing picture.

After installation, open a new shell so the installer’s setup runs, then verify conda is available:

$ conda --version
conda 26.3.2

Conda uses calendar versioning (YY.MM.PATCH), so the exact number depends on when you installed Miniforge. Any recent release is fine.

Note

If you see conda: command not found, the installer didn’t update the shell’s startup files (or you’re still in the pre-install shell). Close the terminal, open a new one, and try again. If it still fails, run the post-install init step: ~/miniforge3/bin/conda init "$(basename "$SHELL")".

Understand what you’ve been given

The environment.yml file describes a conda environment. Here is a realistic example (save this as environment.yml to follow along):

environment.yml
name: analysis
channels:
  - conda-forge
dependencies:
  - python=3.12
  - pandas=2.2
  - matplotlib=3.9
  - scikit-learn=1.5
  - jupyter
  - pip:
    - seaborn

The key fields:

  • name: the environment name. You’ll use this with conda activate analysis.
  • channels: where conda fetches packages. conda-forge is the most common community channel.
  • dependencies: packages installed from conda channels. Version pins like python=3.12 lock to a minor version; unpinned packages like jupyter get the latest compatible release.
  • pip: packages installed from PyPI after the conda packages. Some packages (like seaborn in this example) are available on both conda-forge and PyPI. The pip: section is for packages that are only on PyPI or that the team chose to install via pip.

Create the environment

Run this from the directory that contains environment.yml so conda can find the file:

$ conda env create -f environment.yml
Channels:
 - conda-forge
Platform: linux-64
Collecting package metadata (repodata.json): done
Solving environment: done

Downloading and Extracting Packages: ...

Preparing transaction: done
Verifying transaction: done
Executing transaction: done
Installing pip dependencies: done
#
# To activate this environment, use
#
#     $ conda activate analysis
#
# To deactivate an active environment, use
#
#     $ conda deactivate

This resolves all dependencies, downloads packages, and creates a named environment. The process can take a few minutes on the first run.

Warning

If conda prints EnvironmentFileNotFound: '...environment.yml' file not found, you’re running the command from the wrong directory. Either cd to the directory holding environment.yml or pass an explicit path to -f.

Activate the environment:

$ conda activate analysis
(analysis) $

Notice the (analysis) prefix prepended to your prompt. That prefix tells you the environment is active. Every python, pip, or jupyter command now uses this environment’s packages.

Note

If you see CondaError: Run 'conda init' before 'conda activate', your shell wasn’t set up for activation during the Miniforge install. Run conda init "$(basename "$SHELL")", restart the shell, and try again.

Explore the environment

List installed packages:

(analysis) $ conda list
# packages in environment at /Users/you/miniforge3/envs/analysis:
#
# Name                    Version          Build               Channel
_openmp_mutex             4.5              20_gnu              conda-forge
anyio                     4.13.0           pyhcf101f3_0        conda-forge
...
pandas                    2.2.3            py312hf9745cd_3     conda-forge
...
seaborn                   0.13.2           pypi_0              pypi

This shows every package, its version, build string, and channel. Notice the Channel column: most packages come from conda-forge, but seaborn shows pypi because it was installed by the pip: section of environment.yml. That column is the fastest way to spot the conda/pip boundary in any environment.

The full output is long. Filter it to find a specific package:

(analysis) $ conda list pandas
# packages in environment at /Users/you/miniforge3/envs/analysis:
#
# Name                    Version          Build               Channel
pandas                    2.2.3            py312hf9745cd_3     conda-forge

Check environment metadata:

(analysis) $ conda info

     active environment : analysis
    active env location : /Users/you/miniforge3/envs/analysis
            shell level : 1
       user config file : /Users/you/.condarc
          conda version : 26.3.2
                 solver : libmamba (default)
           channel URLs : https://conda.anaconda.org/conda-forge/...
          package cache : /Users/you/miniforge3/pkgs
       envs directories : /Users/you/miniforge3/envs
               platform : osx-arm64

This prints the active environment path, Python version, and conda configuration. Notice that active env location is a real directory: the environment lives on disk as a folder (typically under ~/miniforge3/envs/analysis/ or wherever Miniforge is installed). Removing the environment later just deletes that folder.

Add a new dependency

Your work requires a package that wasn’t in the original environment.yml. Install it with conda:

(analysis) $ conda install scipy
Channels:
 - conda-forge
Platform: linux-64
Collecting package metadata (repodata.json): done
Solving environment: done

## Package Plan ##

  environment location: /Users/you/miniforge3/envs/analysis

  added / updated specs:
    - scipy

The following NEW packages will be INSTALLED:

  scipy              conda-forge/linux-64::scipy-1.17.1-py312...

Proceed ([y]/n)? y

Downloading and Extracting Packages: ...
Preparing transaction: done
Verifying transaction: done
Executing transaction: done

Conda resolves the new package against everything already installed and updates the environment.

Tip

If the resolver hangs for several minutes or you see LibMambaUnsatisfiableError, conda can’t satisfy your pins together with the new package. Loosen a version pin in environment.yml (drop =2.2 to >=2.2), or install the new package without a version pin and let conda pick.

Handle the conda + pip boundary

Sometimes you need a package that only exists on PyPI, not on conda-forge. Install it with pip inside the active conda environment:

(analysis) $ pip install watermark
Collecting watermark
  Downloading watermark-2.6.0-py3-none-any.whl.metadata (15 kB)
Requirement already satisfied: ipython>=6.0 in /Users/you/miniforge3/envs/analysis/lib/python3.12/site-packages (from watermark) (...)
...
Downloading watermark-2.6.0-py3-none-any.whl (13 kB)
Installing collected packages: watermark
Successfully installed watermark-2.6.0

Notice the Requirement already satisfied lines pointing into miniforge3/envs/analysis/. That’s how you confirm pip is using this environment’s interpreter and not some system Python: every “already satisfied” path should start with the active env’s directory.

Warning

Mixing conda and pip requires care. Always install conda packages first, then pip packages. If you conda install something after using pip, conda doesn’t know about pip’s packages and can overwrite or break them. The safe ordering is: build the conda environment, then add pip packages at the end.

Check what pip sees in the environment (a mix of conda-installed and pip-installed packages):

(analysis) $ pip list --format=freeze | head -20
aiohappyeyeballs==2.6.1
aiohttp==3.12.7
anyio==4.13.0
argon2-cffi==25.1.0
asttokens==3.0.1
async-lru==2.3.0
attrs==26.1.0
babel==2.18.0
beautifulsoup4==4.14.3
bleach==6.3.0
cffi==2.0.0
charset-normalizer==3.4.7
...

The environment.yml captures the conda/pip split with the pip: subsection under dependencies. When you export the environment later, both conda and pip packages are included.

Export the environment for teammates

After adding packages, export the updated environment so teammates can reproduce it.

For cross-platform sharing, use --from-history:

(analysis) $ conda env export --from-history > environment.yml
(analysis) $ cat environment.yml
name: analysis
channels:
  - conda-forge
dependencies:
  - python=3.12
  - jupyter
  - scikit-learn=1.5
  - matplotlib=3.9
  - pip
  - pandas=2.2
  - scipy
prefix: /Users/you/miniforge3/envs/analysis

This exports only the packages you explicitly requested (not platform-specific transitive dependencies), making the file portable across macOS, Linux, and Windows. Notice that scipy is now in the file because you ran conda install scipy earlier; --from-history records every spec you have ever asked for in this environment.

Note

--from-history does not capture pip-installed packages. The watermark package you installed with pip is missing from the export. If your environment includes pip packages, add them manually under a pip: subsection of dependencies: after exporting.

For an exact reproduction on the same platform, export everything:

(analysis) $ conda env export > environment-lock.yml
(analysis) $ head -10 environment-lock.yml
name: analysis
channels:
  - conda-forge
dependencies:
  - _openmp_mutex=4.5=20_gnu
  - anyio=4.13.0=pyhcf101f3_0
  - argon2-cffi=25.1.0=pyhd8ed1ab_0
  - asttokens=3.0.1=pyhd8ed1ab_0
  - attrs=26.1.0=pyhcf101f3_0
  - babel=2.18.0=pyhcf101f3_1

This includes every transitive dependency with exact versions and build strings. It only works on the same OS and architecture.

Remove the environment

When you’re done with an environment or need to start fresh:

(analysis) $ conda deactivate
$ conda env remove -n analysis

Remove all packages in environment /Users/you/miniforge3/envs/analysis:


## Package Plan ##

  environment location: /Users/you/miniforge3/envs/analysis


The following packages will be REMOVED:
  ...

Proceed ([y]/n)? y

Notice the (analysis) prefix vanishes from the prompt after conda deactivate. That confirms you’ve left the environment before removing it; conda refuses to delete the active environment.

Recreate it anytime from the environment.yml file.

Next steps

Last updated on
Setting up testing with pytest and uvTry Free-Threaded Python with uv