Installation

You install simple_module_python by installing its CLI — sm — and using it to scaffold a new app. There's no repo to clone; the framework ships as a set of Python packages on PyPI and the CLI assembles them into a working project for you.

Prerequisites

Tool	Why	How to check
Python 3.12	Runtime	python --version
uv	Python package manager + tool installer	uv --version
Node.js 20+	Vite dev server, React build	node --version
npm 10+	JS workspace manager	npm --version
Docker (optional)	Postgres + Redis when you don't want SQLite	docker --version

On macOS, brew install uv node plus Docker Desktop covers it. On Linux, install uv via the install script and Node via nvm or your package manager.

Install the CLI

uv tool install simple_module_cli

If you prefer pipx:

pipx install simple_module_cli

That puts sm on your PATH globally. Confirm with:

sm --help

Scaffold a new app

sm new myapp

Interactive — you pick the database (SQLite / Postgres), whether to enable multi-tenancy, and which bundled modules to include. Skip the prompts and accept the defaults with:

sm new myapp --yes

Or pick a preset and add modules non-interactively:

sm new myapp --preset standard --with background_tasks,file_storage

Preset	Modules
minimal	auth, users, permissions
standard (default)	minimal + dashboard, settings, feature_flags
full	standard + background_tasks, file_storage

After scaffolding, sm new runs uv sync, npm install, and alembic upgrade head for you (skip with --no-install if you'd rather drive that yourself).

Boot it

cd myapp
make dev

The scaffolded app ships with a small Makefile that runs the API + Vite dev server in parallel:

• uvicorn main:app on :8000 (the FastAPI + Inertia app)
• vite on :5050 (the frontend dev server with HMR)

Hit http://localhost:8000. You should see the landing page.

Database choice

sm new writes a .env.example. The default is SQLite (zero setup):

SM_DATABASE_URL=sqlite+aiosqlite:///./app.db

For Postgres:

SM_DATABASE_URL=postgresql+asyncpg://postgres:postgres@localhost:5432/myapp

The scaffolded docker-compose.yml brings up a postgres container on :5432 (and a redis container on :6379 when you include background_tasks):

docker compose up -d postgres
make migrate

See Configuration for the full list of env vars.

Create the first admin

If you included the users module:

uv run sm-users create-admin --email admin@example.com --password changeme

Or set bootstrap env vars so the admin is auto-created on first boot:

# in .env
SM_USERS_BOOTSTRAP_EMAIL=admin@example.com
SM_USERS_BOOTSTRAP_PASSWORD=changeme

Then make migrate && make dev.

Add a module to your app

sm create-module orders --dest modules/orders

That generates modules/orders/ with the full layout (model, contracts, service, endpoints, pages, tests, locales, pyproject.toml entry point). Add the package to your app's dependencies and re-sync:

uv add ./modules/orders
make dev

The full walkthrough is in Your first module.

Update framework versions

When new releases of simple_module_* ship to PyPI, bump every dep in lockstep:

sm package-update

Pass --dry-run first to preview the diff.

Troubleshooting

sm: command not found after uv tool install. Run uv tool update-shell (or restart your shell) so the tool's bin dir is on PATH.

Port already in use. Free :8000 and :5050 before the next make dev. On Linux/macOS: lsof -ti:8000,5050 | xargs kill -9.

Alembic complains about a revision mismatch. The DB is ahead of or behind the migration files. For a dev DB: rm app.db && make migrate. For Postgres: docker compose down -v && docker compose up -d postgres && make migrate.

Entry points aren't discovered after editing a module's pyproject.toml. Re-run uv sync — entry points are registered at install time, not at import time.

Next steps

• Quickstart — bootstrap and tour the running app in five minutes.
• Project structure — what sm new lays down.
• Your first module — extend the app with your own domain logic.
• Bundled modules — what each pre-installed module ships.