# Take over an existing conda environment

You just joined a team or lab that uses [conda](https://pydevtools.com/handbook/reference/conda.md). 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](https://github.com/conda-forge/miniforge#install).

> [!IMPORTANT]
> Use Miniforge, not Miniconda or Anaconda. Miniforge defaults to the [conda-forge](https://pydevtools.com/handbook/reference/conda-forge.md) 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?](https://pydevtools.com/handbook/explanation/is-conda-actually-free.md) for the full licensing picture.

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

```console
$ 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):

```yaml {filename="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](https://pypi.org) 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:

```console
$ 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:

```console
$ 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:

```console
(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:

```console
(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:

```console
(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:

```console
(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:

```console
(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):

```console
(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`:

```console
(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:

```console
(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:

```console
(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

- [Understanding the Conda/Anaconda Ecosystem](https://pydevtools.com/handbook/explanation/understanding-the-conda-anaconda-ecosystem.md) for a map of how conda, Anaconda, Miniforge, and conda-forge relate
- [Is Conda Actually Free?](https://pydevtools.com/handbook/explanation/is-conda-actually-free.md) for licensing details
- [uv vs pixi vs conda for Scientific Python](https://pydevtools.com/handbook/explanation/uv-vs-pixi-vs-conda-for-scientific-python.md) to compare conda with modern alternatives
- [How to Migrate from Conda to pixi](https://pydevtools.com/handbook/how-to/how-to-migrate-from-conda-to-pixi.md) to modernize an existing conda workflow