PyPSA App

Self-hosted web application for analyzing and visualizing PyPSA networks, with modular architecture designed to extend into workflow execution, network editing, optimization, and custom integrations.

Running the App

Both modes require the frontend to be running on the host. See Frontend below.

Containerized mode (supported)

Runs the full backend stack in Docker (Postgres, Redis, Celery worker, and the Python API). This is the supported way to verify the app works end to end.

Requirements: Docker with Compose

docker compose -f compose/compose.yaml --env-file compose/.env.local up --build

API docs available at http://localhost:8000/docs.

Dev mode (for developer convenience)

Runs infrastructure services in Docker while the API runs on the host, enabling hot-reload and faster iteration during development.

Requirements:

• Python ≥ 3.13 + uv
• Docker with Compose

1. Start Postgres, Redis, and the Celery worker

docker compose -f compose/compose.services.yaml --env-file compose/.env.local up

2. Run the backend API

uv run --extra full --env-file compose/.env.local pypsa-app serve --reload

API docs available at http://localhost:8000/docs.

Frontend

Applies to both modes. Requires Node.js 22.x.

cd frontend/app
npm install
npm run dev

App available at http://localhost:5173.

Running Tests

Requirements: Python ≥ 3.13 + uv

Install dev dependencies (first time only):

uv sync --extra dev

Run the test suite:

uv run pytest

With coverage:

uv run pytest --cov

Migration tests also run against Postgres if TEST_POSTGRES_URL is set:

TEST_POSTGRES_URL=postgresql://user:pass@localhost/testdb uv run pytest

License

The PyPSA App is licensed under the AGPL-3.0 license.