Skip to content

Commit

Permalink
Fixes to docs on user environments. (#1149)
Browse files Browse the repository at this point in the history
Closes #1148
  • Loading branch information
molpopgen authored Apr 3, 2023
1 parent f747f47 commit 16cec5d
Showing 1 changed file with 1 addition and 53 deletions.
54 changes: 1 addition & 53 deletions doc/pages/userenv.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ mkdir ~/venvs
python3 -m venv ~/venvs/fwdpy11
source activate ~/venvs/fwdpy11/bin/activate
python -m pip install --upgrade pip
pip install fwpdy11
python -m pip install fwpdy11
```

:::{note}
Expand Down Expand Up @@ -64,55 +64,3 @@ channels:
```

:::

### Working in "environments"

:::{note}

The stability of conda installation into environments is a moving target.
We will try to keep this up to date.

:::

Many users prefer to set up different environments for different projects.
Doing so requires some care.
Currently, `conda-forge`, the channel from which `bioconda` pulls dependencies, builds for Python versions not supported by `bioconda`.
Thus, building an environment like this will often lead to failure:

```{code-block} bash
conda create -n myenv -y
```

The problem here is that installing dependencies that are *not* from `bioconda` is likely to pull in Python 3.9, leaving you unable to install `bioconda` packages.
(Currently, `bioconda` only supports up to Python 3.8.)

Unfortunately, creating a new environment based on Python 3.8 will also lead to failure:

```{code-block} bash
conda create -n myenv python=3.8 -y
```

The problem here is that the Python 3.8 build will be upgraded compared to what came with `miniconda`.
For reasons that we are unable to understand, this upgrade leads to run-time problems in some instances.

Thus, the safest thing to do is to clone your `base`:

```{code-block} bash
conda create -n myenv --clone base
```

Now, `myenv` is an exact copy of `base`, and you can `conda install fwdpy11` successfully.
This solution is safest if you never install anything into `base`, leaving it as it was when you installed `miniconda`.

:::{warning}

When working in environments, never `conda update`!
Updating is likely to do *bad things* to dependencies that you won't notice until you run something.

:::

0 comments on commit 16cec5d

Please sign in to comment.