Local venv is missing requirements.txt dependencies; first-run install not documented #42

New issue

Closed

opened 2026-06-22 16:23:20 +00:00 by Mark · 0 comments

Mark commented

2026-06-22 16:23:20 +00:00

Owner

Repro

cd /home/b/Projects/easystitch
source .venv/bin/activate
python -c "from main_pipeline import EmbroideryPipeline"
# ModuleNotFoundError: No module named 'defusedxml'

defusedxml is in requirements.txt but not in the local .venv/. Same
likely true for several other deps (lxml, pyembroidery, scikit-image,
scikit-learn, pydantic, python-dotenv, matplotlib, aiohttp).

Impact

A new contributor who clones the repo and tries to run the tests (or the
service per "Add HTTP service layer") hits ModuleNotFoundError immediately.
The fix is pip install -r requirements.txt, but that's not documented.

The Dockerfile hides this because it installs requirements in the build
step. The local venv doesn't.

Fix

Document install: add a "First time setup" section to README:

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
pip install -e .  # editable install so `import` works

Make the venv reproducible: pin versions in requirements.txt (or
generate requirements.lock) so pip install -r is deterministic.
CI should run the same steps the local developer is told to run.
Pre-commit hook: check that the venv has all requirements installed
and warn if not.

Acceptance

README has a "First time setup" section that works.
A fresh python3 -m venv .venv && source .venv/bin/activate && pip install -r requirements.txt && pip install -e . allows python -c "import main_pipeline" to succeed.
CI runs the same flow.

## Repro ```bash cd /home/b/Projects/easystitch source .venv/bin/activate python -c "from main_pipeline import EmbroideryPipeline" # ModuleNotFoundError: No module named 'defusedxml' ``` `defusedxml` is in `requirements.txt` but not in the local `.venv/`. Same likely true for several other deps (`lxml`, `pyembroidery`, `scikit-image`, `scikit-learn`, `pydantic`, `python-dotenv`, `matplotlib`, `aiohttp`). ## Impact A new contributor who clones the repo and tries to run the tests (or the service per "Add HTTP service layer") hits `ModuleNotFoundError` immediately. The fix is `pip install -r requirements.txt`, but that's not documented. The Dockerfile hides this because it installs requirements in the build step. The local venv doesn't. ## Fix 1. **Document install:** add a "First time setup" section to README: ```bash python3 -m venv .venv source .venv/bin/activate pip install -r requirements.txt pip install -e . # editable install so `import` works ``` 2. **Make the venv reproducible:** pin versions in `requirements.txt` (or generate `requirements.lock`) so `pip install -r` is deterministic. 3. **CI should run the same steps** the local developer is told to run. 4. **Pre-commit hook:** check that the venv has all requirements installed and warn if not. ## Acceptance - README has a "First time setup" section that works. - A fresh `python3 -m venv .venv && source .venv/bin/activate && pip install -r requirements.txt && pip install -e .` allows `python -c "import main_pipeline"` to succeed. - CI runs the same flow.