diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml
index a3da887..2c6a042 100644
--- a/.github/workflows/deploy.yml
+++ b/.github/workflows/deploy.yml
@@ -45,7 +45,7 @@ jobs:
       - name: Set up conda environment
         uses: mamba-org/setup-micromamba@v1
         with:
-            environment-file: build_envs/docs.yml
+            environment-file: environments/docs.yml
             cache-environment: true
             cache-environment-key: "docs-${{env.TODAY}}"
             create-args: >-
@@ -99,4 +99,4 @@ jobs:
 
       - name: Deploy to GitHub Pages
         id: deployment
-        uses: actions/deploy-pages@v2
\ No newline at end of file
+        uses: actions/deploy-pages@v2
diff --git a/README.md b/README.md
index 4baa233..18d5477 100644
--- a/README.md
+++ b/README.md
@@ -30,15 +30,18 @@ $ ./manage_externals/checkout_externals
 Then build the necessary conda environments with
 
 ```
-$ conda env create -f cupid/dev-environment.yml
+$ mamba env create -f environments/dev-environment.yml
 $ conda activate cupid-dev
 $ which cupid-run
-$ conda env create -f cupid-analysis.yml
+$ mamba env create -f environments/cupid-analysis.yml
 ```
 
 Notes:
 
-1. `conda` now defaults to using `mamba` to solve environments; the `cupid-analysis.yml` environment is complicated, so older versions of `conda` should be updated (`conda update -n base conda`) or you should use `mamba` instead.
+1. As of version 23.10.0, `conda` defaults to using `mamba` to solve environments.
+It still feels slower than running `mamba` directly, hence the recommendation to install with `mamba env create` rather than `conda env create`.
+If you do not have `mamba` installed, you can still use `conda`... it will just be significantly slower.
+(To see what version of conda you have installed, run `conda --version`.)
 1. If `./manage_externals/checkout_externals` is not found, run `git submodule update --init` to clone the submodule.
 1. If `which cupid-run` returned the error `which: no cupid-run in ($PATH)`, then please run the following:
 
diff --git a/cupid/dev-environment.yml b/cupid/dev-environment.yml
deleted file mode 100644
index a821d37..0000000
--- a/cupid/dev-environment.yml
+++ /dev/null
@@ -1,6 +0,0 @@
-name: cupid-dev
-dependencies:
-    - python==3.11.4
-    - pip
-    - pip:
-      - -e ../
diff --git a/environments/README b/environments/README
new file mode 100644
index 0000000..60310aa
--- /dev/null
+++ b/environments/README
@@ -0,0 +1,10 @@
+This directory contains three conda environment files:
+
+1. dev-environment.yml: this creates (cupid-dev), which provides cupid-run and cupid-build,
+                        and lets users update the main CUPiD code in cupid/
+
+2. cupid-analysis.yml: this creates (cupid-analysis), the environment all scripts and notebooks
+                       run in
+
+3. docs.yml: this creates (cupid-docs), which is used by github actions to build
+             https://ncar.github.io/CUPiD
diff --git a/cupid-analysis.yml b/environments/cupid-analysis.yml
similarity index 100%
rename from cupid-analysis.yml
rename to environments/cupid-analysis.yml
diff --git a/environments/dev-environment.yml b/environments/dev-environment.yml
new file mode 100644
index 0000000..58f940d
--- /dev/null
+++ b/environments/dev-environment.yml
@@ -0,0 +1,18 @@
+name: cupid-dev
+dependencies:
+    - python=3.11.4
+    - black
+    - dask
+    - dask-jobqueue
+    - intake
+    - intake-esm
+    - jinja2
+    - jupyter-book
+    - pandas
+    - papermill
+    - pip
+    - ploomber=0.22.3
+    - pyyaml
+    - xarray
+    - pip:
+      - -e ../
diff --git a/build_envs/docs.yml b/environments/docs.yml
similarity index 100%
rename from build_envs/docs.yml
rename to environments/docs.yml