diff --git a/.github/workflows/code_tests.yml b/.github/workflows/code_tests.yml
index 1adcaa3e5..aceadbaec 100644
--- a/.github/workflows/code_tests.yml
+++ b/.github/workflows/code_tests.yml
@@ -35,7 +35,7 @@ jobs:
 
     # Install swell
     - name: Install swell and dependencies
-      run: pip3 install -v --no-cache-dir --use-deprecated=legacy-resolver -r requirements-github.txt --user .
+      run: pip3 install -v --no-cache-dir --user .[github]
 
     # Put swell executables in the path
     - name: Put swell in the path
diff --git a/docs/platforms/discover/installing_swell_csh_interactive.md b/docs/platforms/discover/installing_swell_csh_interactive.md
index 60f16f2a0..636a0f4ff 100644
--- a/docs/platforms/discover/installing_swell_csh_interactive.md
+++ b/docs/platforms/discover/installing_swell_csh_interactive.md
@@ -39,8 +39,7 @@ git clone https://github.com/GEOS-ESM/swell.git swell-develop
 4) Load all the modules that Swell needs: `mod_swell` (this is the `csh` alias function created in the preliminary steps)
 5) Create a Python virtual environment: `python3 -m venv .venv`
 6) Activate the virtual environment: `source .venv/bin/activate.csh`
-7) Install Swell dependencies: `pip install -r --ignore-installed requirements.txt`
-8) Install swell in editable mode: `pip install -e .` (note: make sure you run this while the `venv` is active)
+7) Install swell in editable mode: `pip install -e .` (note: make sure you run this while the `venv` is active)
 
 9) Now, work on SWELL. Any changes you make to the SWELL source code will be automatically applied to the install (because it's an editable install); no need to manually reinstall.
 
diff --git a/docs/platforms/discover/installing_swell_uv_offline.md b/docs/platforms/discover/installing_swell_uv_offline.md
index 75842136d..f6b36f05b 100644
--- a/docs/platforms/discover/installing_swell_uv_offline.md
+++ b/docs/platforms/discover/installing_swell_uv_offline.md
@@ -34,7 +34,8 @@ We will download all the required packages on local with the corresponding pytho
 
     mkdir ../downloaded  # where offline packages will be saved to
     pip3 download "setuptools>=68.0.0" -d ../downloaded
-    pip3 download -r requirements.txt -d ../downloaded  
+    pip3 download "wheel>=0.46.3" -d ../downloaded
+    pip3 download . -d ../downloaded
 ```
 3. Upload the packages under `downloaded` to a Discover directory, `[discover_offline_pkg_path]`
 4. On a milan node from Discover, install the packages by
@@ -53,14 +54,13 @@ We will download all the required packages on local with the corresponding pytho
     source .venv/bin/activate
     which pip3    # ensure pip3 points to the same dir as python under your venv
     # (optional_end)
-    pip3 install --no-index --find-links=[discover_offline_pkg_path] -r requirements.txt
 ```
 5. Install SWELL in editable mode 
 ```
     deactivate 
     mod_swell
     source .venv/bin/activate
-    python -m pip install -e .
+    python -m pip install --no-index --find-links=[discover_offline_pkg_path] -e .
 ```
 #### Reuse SWELL and launch SWELL jobs
 Log into a **Milan** node on Discover, run 
diff --git a/docs/platforms/discover/installing_swell_uv_venv.md b/docs/platforms/discover/installing_swell_uv_venv.md
index 37326491d..b1c09028e 100644
--- a/docs/platforms/discover/installing_swell_uv_venv.md
+++ b/docs/platforms/discover/installing_swell_uv_venv.md
@@ -36,9 +36,8 @@ git clone https://github.com/GEOS-ESM/swell.git swell-develop
 4) Load all the modules that SWELL needs: `mod_swell` (this is the `bash` function created in the preliminary steps)
 5) Create a Python virtual environment: `uv venv`
 6) Activate the virtual environment: `source .venv/bin/activate`
-7) Install SWELL dependencies `uv pip install -r requirements.txt`
-8) Install SWELL in editable mode: `python -m pip install -e .`. (note: make sure you run this while the `venv` is active)
-9) Now, work on SWELL. Any changes you make to the SWELL source code will be automatically applied to the install (because it's an editable install); no need to manually reinstall.
+7) Install SWELL in editable mode: `uv pip install -e .`. (note: make sure you run this while the `venv` is active)
+8) Now, work on SWELL. Any changes you make to the SWELL source code will be automatically applied to the install (because it's an editable install); no need to manually reinstall.
 
 #### Resuming work from a previous SWELL installation:
 1) Switch to your folder where SWELL is installed: `cd $NOBACKUP/swell-project/mybranch`.
diff --git a/pyproject.toml b/pyproject.toml
index 0ebf0cc6c..a2c9b528a 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -32,6 +32,35 @@ classifiers = [
 "Operating System :: OS Independent"
 ]
 
+dependencies = [
+    "click>=8.0.0",
+    "jinja2>=3.0.3",
+    "pyyaml>=6.0",
+    "pycodestyle>=2.11.0",
+    "numpy<2",
+    "pandas>=1.4.0",
+    "isodate>=0.5.4",
+    "f90nml>=1.4.3",
+    "questionary>=1.10.0",
+    "h5py>=3.7.0",
+    "flake8==6.1.0",
+    "netCDF4",
+    "ruamel.yaml==0.17.16"
+]
+
+[project.optional-dependencies]
+github = [
+    "click==8.1.5",
+    "jinja2==3.1.2",
+    "pyyaml==6.0.1",
+    "pandas>=1.4.0",
+    "numpy==1.26.0",
+    "isodate==0.6.1",
+    "f90nml==1.4.4",
+    "questionary==1.10.0",
+    "netCDF4==1.6.5",
+]
+
 [project.urls]
 Repository = "https://github.com/geos-esm/swell"
 Documentation = "https://geos-esm.github.io/swell/#/"
diff --git a/requirements-github.txt b/requirements-github.txt
deleted file mode 100644
index 5746714e0..000000000
--- a/requirements-github.txt
+++ /dev/null
@@ -1,12 +0,0 @@
-click==8.1.5
-jinja2==3.1.2
-pyyaml==6.0.1
-pycodestyle==2.10.0
-pandas>=1.4.0
-numpy==1.26.0
-isodate==0.6.1
-f90nml==1.4.4
-questionary==1.10.0
-flake8==6.0.0
-netCDF4==1.6.5
-ruamel.yaml==0.17.16
diff --git a/requirements.txt b/requirements.txt
index 4d0999ba7..b3238c685 100644
--- a/requirements.txt
+++ b/requirements.txt
@@ -1,3 +1,5 @@
+# Warning: as of PR #686, requirements.txt is deprecated, and will be deleted in the future.
+# Dependencies should be handled using pyproject.toml.
 click>=8.0.0
 jinja2>=3.0.3
 pyyaml>=6.0