air: Build Python Web Apps with HTML and FastAPI

Overview

Air is a Python framework for creating server-rendered web pages and APIs in one application. Built on FastAPI, Pydantic, and HTMX, it addresses the friction of returning HTML from FastAPI by providing page helpers, a Jinja renderer, and Python classes for composing HTML.

It is aimed at developers who prefer explicit, typed interfaces and want AI coding assistants to work from code and docstrings rather than relying on hidden conventions. Air is most relevant for new Python web projects that need both conventional HTML pages and API endpoints.

Key Features

• Define page routes with @app.page and return HTML directly.
• Build markup with typed Python HTML classes, or render existing Jinja templates.
• Combine Air pages and FastAPI routes in one app, including mounted FastAPI sub-apps.
• Use FastAPI capabilities such as OpenAPI documentation, response models, and WebSockets alongside pages.
• Validate HTML form input with Pydantic using Air Forms.
• Use utilities designed to work with HTMX.
• Provides in-source types and documentation intended to make the API understandable to AI coding tools.

Use Cases

• Build a server-rendered site in Python when you want HTML pages without setting up a separate frontend application.
• Add web pages to an existing FastAPI service while retaining its API routes and tooling.
• Develop form-heavy applications where Pydantic validation can be shared with Python code.
• Prototype pages from HTML mockups using Jinja, then use Python-generated markup where typed editor support is useful.

Project Facts

• Language: Python
• License: MIT
• Stars: 920
• Forks: 100
• Topics: ai, fastapi, pydantic, python, starlette, web
• Archived: No

Getting Started

Install Air with uv:

uv add air

For setup options and examples, see the README and documentation.

Alternatives

• Masonite: Masonite is a broader Python web framework with built-in ORM, mail, queues, and scheduling, rather than a FastAPI-focused framework for typed HTML and HTMX.

Considerations

• The README identifies Air as alpha and warns that APIs may change between releases.
• Air is built on FastAPI and Pydantic, so it is best suited to teams working in Python and comfortable with that ecosystem.
• The project keeps its core intentionally minimal. The README recommends discussing feature ideas in an issue and notes that additional features may belong in separate ecosystem packages.
• AI-assisted development is a design goal, not a requirement; the framework can also be used directly by developers.