Skip to main content

Developing on Windows

Notes for getting the Python workspace and its test suite running on Windows.

The Makefile, install.sh, and make targets are Unix-oriented (they call ./install.sh and source venv/bin/activate), so they don't work as-is from a Windows shell. These steps cover the uv workspace path, which installs the local packages/* so imports such as from llm.gemini.transcript_cache_paths import ... resolve. PowerShell is assumed.

Prerequisites​

  • Python 3.11+ (the workspace targets >=3.11)
  • uv
  • Git

Setup​

From the repository root:

uv sync

This creates .venv and installs the workspace members (communityone-core, communityone-llm, communityone-scrapers, …) in editable mode, which is what makes the top-level llm, scrapers, ingestion, … imports work.

Then install two things uv sync does not pull in:

uv pip install pytest black ruff
uv pip install yt-dlp

Why these are needed on the uv path:

  • Test/lint tools. pytest, black, and ruff are listed in the root requirements.txt, but uv sync resolves only the workspace packages' declared dependencies and there is no uv dev-dependency group, so they are not installed. (The pip path below installs them via requirements.txt.)
  • yt-dlp. Importing the Gemini transcript-cache modules transitively pulls in scrapers.youtube, which imports yt_dlp at module load. yt-dlp is in requirements.txt but is not declared as a dependency of any workspace package, so uv sync leaves it out. Without it, test collection fails with ModuleNotFoundError: No module named 'yt_dlp'.

Running tests on Windows​

Run the test suite through the venv's own interpreter:

.venv\Scripts\python -m pytest tests\test_transcript_cache_geography.py -v --basetemp=.pytest_basetemp

Two Windows-specific reasons for this exact form:

  • .venv\Scripts\python -m pytest, not a bare pytest or uv run pytest. A bare pytest can resolve to a different interpreter on PATH (for example an Anaconda base environment) where the workspace packages are not installed, giving ModuleNotFoundError: No module named 'llm'. uv run re-syncs the environment first, which can drop the ad-hoc uv pip installed tools above. Invoking the venv's Python directly avoids both.
  • --basetemp=.pytest_basetemp. Pytest's default temp directory (%LOCALAPPDATA%\Temp\pytest-of-<user>) can raise PermissionError: [WinError 5] Access is denied on some Windows setups. Pointing --basetemp at a folder inside the repo sidesteps it. (Add .pytest_basetemp/ to your local ignores if it isn't already covered.)

Troubleshooting​

SymptomCauseFix
ModuleNotFoundError: No module named 'llm'pytest ran under a different Python (e.g. Anaconda base)run .venv\Scripts\python -m pytest …
ModuleNotFoundError: No module named 'yt_dlp'not in the uv workspace closureuv pip install yt-dlp
pytest / black / ruff not recognisednot in the uv workspace closureuv pip install pytest black ruff
PermissionError: [WinError 5] Access is denied during test setupWindows temp-dir permissionsadd --basetemp=.pytest_basetemp
Tools disappear after uv runuv run re-syncs and drops ad-hoc installsuse .venv\Scripts\python -m pytest

Alternative: the pip path​

CI installs the backend with pip rather than uv, and requirements.txt includes pytest, black, ruff, and yt-dlp. To mirror that locally:

python -m venv .venv
.venv\Scripts\Activate.ps1
pip install -r requirements.txt
pip install --no-deps -e packages/core -e packages/datamodels -e packages/agents -e packages/ingestion -e packages/llm

The -e packages/* editable installs are what make llm, ingestion, etc. import as top-level modules (see .github/workflows/ci-build-test.yml).