diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index 61baecdd..4fbf377a 100644
--- a/.github/workflows/test.yml
+++ b/.github/workflows/test.yml
@@ -131,32 +131,27 @@ jobs:
       - name: Install dev dependencies
         run: ./wrappers/python/scripts/ci/github/install_dev_dependencies.sh
 
-      - name: activate venv on windows
-        if: runner.os == 'Windows'
-        shell: pwsh
-        working-directory: ./wrappers/python
-        run: .\.venv\Scripts\Activate.ps1
-      
+      - name: activate venv
+        run: ./wrappers/python/scripts/ci/github/activate_venv.sh
+
       - name: debug python paths
         run: ./wrappers/python/scripts/ci/github/debug_python_paths.sh
 
       - name: Lint python
-        # if: runner.os == 'Linux'
+        # avoid duplicating linting work on different OSes
+        if: runner.os == 'Linux'
         working-directory: ./wrappers/python
-        run: |
-          export VIRTUAL_ENV="$PWD/.venv"
-          export PATH="$VIRTUAL_ENV/bin:$PATH"
-          bash ./scripts/ci/python_lints.sh
-
+        run: ./scripts/ci/python_lints.sh
+        
       - name: ensure cog up-to-date
+        # avoid duplicating linting work on different OSes
         if: runner.os == 'Linux'
         working-directory: ./wrappers/python
-        run: |
-          export VIRTUAL_ENV="$PWD/.venv"
-          export PATH="$VIRTUAL_ENV/bin:$PATH"
-          ./scripts/ci/cog/check.sh
+        run: ./scripts/ci/cog/check.sh
 
       - name: Test python API
         timeout-minutes: 1
+        # ^ guard against the tests getting deadlock if the subprocess pipe
+        # gets clogged
         run: ./wrappers/python/scripts/ci/github/integration_tests.sh
 
diff --git a/wrappers/python/scripts/build/all.py b/wrappers/python/scripts/build/all.py
index 65c53317..946e615d 100644
--- a/wrappers/python/scripts/build/all.py
+++ b/wrappers/python/scripts/build/all.py
@@ -1,8 +1,10 @@
+"""A script that builds all the pagefind binary-only wheels."""
+
 import os
 import tarfile
 import tempfile
 from pathlib import Path
-from typing import List, Optional
+from typing import List, Optional, Tuple
 from argparse import ArgumentParser
 
 from . import dist_dir, setup_logging
@@ -49,7 +51,7 @@ def check_platforms(certified: List[Path]) -> None:
         raise ValueError(err_message)
 
 
-def parse_args():
+def parse_args() -> Tuple[bool, Optional[Path]]:
     parser = ArgumentParser()
     parser.add_argument("--dry-run", action="store_true")
     parser.add_argument("DIR", type=Path, default=None, nargs="?")
diff --git a/wrappers/python/scripts/ci/github/activate_venv.sh b/wrappers/python/scripts/ci/github/activate_venv.sh
new file mode 100755
index 00000000..1b0c681b
--- /dev/null
+++ b/wrappers/python/scripts/ci/github/activate_venv.sh
@@ -0,0 +1,25 @@
+#!/usr/bin/env bash
+set -eu
+
+cd wrappers/python
+
+VIRTUAL_ENV="$PWD/.venv"
+echo "VIRTUAL_ENV=$VIRTUAL_ENV" >> "$GITHUB_ENV"
+
+if ! [ -d "$VIRTUAL_ENV" ]; then
+  echo "No virtualenv found at $VIRTUAL_ENV"
+  exit 127
+fi
+
+# Ensure binaries from the virtualenv are available at the start of $PATH
+# see https://docs.python.org/3/library/venv.html#creating-virtual-environments
+if [ -d "$VIRTUAL_ENV/bin" ]; then
+  # on unix systems, virtualenv puts executables in .venv/bin
+  venv_bin_path="$VIRTUAL_ENV/bin"
+elif [ -d "$VIRTUAL_ENV/Scripts" ]; then
+  # on windows, virtualenv places executables in .venv/Scripts
+  venv_bin_path="$VIRTUAL_ENV/Scripts"
+fi
+
+echo "$venv_bin_path" >> "$GITHUB_PATH"
+# see https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/workflow-commands-for-github-actions#adding-a-system-path
diff --git a/wrappers/python/scripts/ci/github/debug_python_paths.sh b/wrappers/python/scripts/ci/github/debug_python_paths.sh
index 580cb601..1cee4911 100755
--- a/wrappers/python/scripts/ci/github/debug_python_paths.sh
+++ b/wrappers/python/scripts/ci/github/debug_python_paths.sh
@@ -1,15 +1,34 @@
 #!/usr/bin/env bash
 set -eu
 cd wrappers/python
-export VIRTUAL_ENV="$PWD/.venv"
-export PATH="$VIRTUAL_ENV/bin:$PATH"
+
+echo "VIRTUAL_ENV=$VIRTUAL_ENV"
+
 # shellcheck disable=SC2016
 echo '$PATH:'
-echo "$PATH" | tr ':' '\n  - '
+echo "$PATH" | tr ':' '\n' | sed 's/^/  - /g'
+
+echo
+echo " python ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ "
+echo
 
+python --version
 command -v python
 command -v python3
+stat ./.venv/bin/python \
+  || stat ./.venv/Scripts/python.exe \
+  || echo "missing .venv/bin/python{.exe}"
+
+echo
+echo " poetry ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ "
+echo
+
 command -v poetry || echo "missing poetry"
+
+echo
+echo " mypy ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ "
+echo
+
 if ! command -v mypy; then 
   if command -v mypy.exe; then
     echo "missing mypy, but found mypy.exe"
@@ -17,5 +36,4 @@ if ! command -v mypy; then
     echo "missing mypy{.exe}"
   fi
 fi
-stat ./.venv/bin/python || stat ./.venv/bin/python.exe || echo "missing .venv/bin/python{.exe}"
-python --version
+
diff --git a/wrappers/python/scripts/ci/github/integration_tests.sh b/wrappers/python/scripts/ci/github/integration_tests.sh
index 5029d23d..c7887b23 100755
--- a/wrappers/python/scripts/ci/github/integration_tests.sh
+++ b/wrappers/python/scripts/ci/github/integration_tests.sh
@@ -2,11 +2,12 @@
 set -eu
 export PATH="$PWD/target/release:$PATH"
 export PYTHONPATH="$PWD/wrappers/python/src:${PYTHONPATH:-}"
+# ^ ensure `import pagefind` imports wrappers/python/src/pagefind/__init__.py
 export PAGEFIND_PYTHON_LOG_LEVEL=DEBUG
 
 cd wrappers/python
-python3 -c 'import sys; print("pythonpath\n" + "\n".join(sys.path))'
-python3 -c '
+python -c 'import sys; print("pythonpath\n  - " + "\n  - ".join(sys.path))'
+python -c '
 import logging
 import os
 from pagefind.service import get_executable
@@ -15,5 +16,5 @@ logging.basicConfig(level=os.environ.get("PAGEFIND_PYTHON_LOG_LEVEL", "INFO"))
 print(get_executable())
 '
 
-python3 -m pagefind --help
-python3 src/tests/integration.py
+python -m pagefind --help
+python src/tests/integration.py
diff --git a/wrappers/python/scripts/ci/python_lints.sh b/wrappers/python/scripts/ci/python_lints.sh
index 5206b242..eaad2b7e 100755
--- a/wrappers/python/scripts/ci/python_lints.sh
+++ b/wrappers/python/scripts/ci/python_lints.sh
@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
 set -eu
-python3 -m mypy src scripts
-python3 -m ruff check
-python3 -m ruff format --check
+mypy src scripts
+ruff check
+ruff format --check