A Rails-inspired Python MVC framework built on Flask, SQLAlchemy, and Celery.

Flask handles HTTP requests, SQLAlchemy and Alembic handle the database, and Celery runs background jobs.

Models, controllers, and templates live in conventional directories. The framework discovers them without manual registration. Flask APIs and extensions remain available when you need them.

What's included

• Resource routing with CRUD routes and path helpers.
• Models with associations, validations, and lifecycle callbacks.
• Jinja templates, form helpers, and HTML or JSON responses.
• Generators for models, migrations, controllers, scaffolds, mailers, and authentication.
• Background jobs and email delivery.
• File attachments with disk and S3-compatible storage.
• Environment settings, database.yml, encrypted credentials, and boot-time initializers.
• Pytest-based transactional tests, YAML fixtures, job and mail assertions, and Playwright browser tests.

Installation

Requires Python 3.12 or newer. Install Flaskteroids in your Python environment:

pip install flaskteroids

Getting started

Create an application. Git, Bash, and uv must be installed.

flaskteroids new my_app
cd my_app
source .venv/bin/activate

Generation installs dependencies and prepares your development database. Start the server:

flask run

Open http://127.0.0.1:5000 to see the welcome page.

flask test
flask test:system

The app includes a health test. An empty system suite succeeds without a browser.

Add a posts resource

Stop the server and run these commands inside my_app:

flask generate scaffold Post title:string content:text
flask db:prepare
flask run

The scaffold generates a model, migration, controller, views, and routes. Visit http://127.0.0.1:5000/posts/ to create, view, edit, and delete posts.

Next steps

For a step-by-step tutorial, follow Getting started with Flaskteroids. Build a product catalog while learning models, controllers, forms, authentication, uploads, email, and testing.

• Run bin/setup for a fresh checkout or after changing dependencies. Commit uv.lock.
• To defer installation, use flaskteroids new my_app --skip-install, then run bin/setup later.
• See Testing for browser setup and Configuration for environments and secrets.
• Your generated deploy/README.md explains Docker and deployment.

See the documentation for the API guides.

Agent skills

Flaskteroids bundles coding guidance for agents with each release. New applications include .agents/skills/using-flaskteroids/SKILL.md, which points agents to instructions for the installed framework version. These instructions require agents to use public Flaskteroids APIs when they cover the task, rather than calling dependency internals.

In your application's Python environment, locate the installed skills with:

flaskteroids agent-skills path

The command prints the absolute skills directory path. Read using-flaskteroids/SKILL.md inside that directory for version-matched guidance. No application configuration or initialization is required.

Development

Use the committed lock and the same check-only commands as CI:

uv sync --locked --dev
uv run ruff check .
uv run ruff format --check .
uv run mypy
uv run playwright install chromium
uv run pytest -q

Ruff uses the Python 3.12 / 88-column policy in pyproject.toml. Mypy checks only declaration records, queue adapters, and a static contract probe, not the whole ORM or generated applications. Raw Mako templates are excluded; generated samples are validated separately and are not promised Ruff-clean. See AGENTS.md for scope and contributor-only fixing commands. Repository logos and usage guidance are in branding/.

Releasing

See the release guide for release PRs and PyPI publishing.

License

Flaskteroids is released under the MIT License.