FastHTML: a Python web framework where HTML, HTMX and HTTP map 1:1

What FastHTML is for, and who should reach for it

FastHTML targets a specific kind of Python developer: someone who wants a web page that reacts to clicks, and does not want to write a JavaScript front end to get it. The README describes the project as a web framework for "fast, scalable web applications with minimal, compact code", and it is explicit that FastHTML's functionality maps 1:1 to HTML and HTTP. That mapping is the whole design premise. A route returns an HTML element, not a JSON payload, and the browser swaps that element into the existing page.

The intended audience is narrower than a general web framework's. The README warns that you will need to understand HTML and HTTP foundations to use the library fully. If you have never thought about what a POST body looks like or how a form serialises, FastHTML will not hide that from you. Developers coming from Flask or FastAPI will recognise the routing decorator; developers coming from React will find the component model familiar but the execution model inverted, because the markup is produced on the server for every interaction.

The project is distributed on PyPI as python-fasthtml, which is worth noting because the import name and the install name differ. The repository is not archived, and the last push was on 2026-09-21, with release 0.14.13 published on 2026-09-03. The package metadata classifies the development status as Alpha, so the version numbers are not a signal of API freeze.

How FastHTML works: routes, Python elements and HTML partials

The mechanism is short enough to describe in a paragraph. You create an app and a router with fast_app(), decorate a function with @rt('/path'), and return an object built from the HTML element classes that fasthtml.common exports. Those element classes come from fastcore.xml.FT, which the README names as what FastHTML uses behind the scenes. Calling serve() starts a server, and the README says running the app prints a link to http://localhost:5001.

Interactivity comes from HTMX attributes attached to those elements. In the README's example, a Div contains a P with hx_get="/change". Clicking that element makes the browser issue a GET to /change, and the route returns another element. The README calls the response an "HTML partial", meaning a snippet of HTML that is inserted into the existing page. The default HTMX behaviour replaces the original element with the returned one.

That is the entire data flow: browser event, HTTP request, Python function, HTML fragment, DOM swap. There is no client-side state store and no serialisation layer between the server and the view. The trade-off is that every interaction costs a round trip, so a control that must respond instantly on a slow connection needs thought. The upside is that the server is the single source of truth, and you can debug an interaction by reading the route that produced the fragment.

The dependency list in pyproject.toml shows what sits underneath: starlette for the ASGI layer, uvicorn[standard] as the server, python-multipart for form bodies, itsdangerous and oauthlib for session and auth plumbing, and beautifulsoup4. FastHTML is a thin layer over an existing ASGI stack rather than a new runtime.

Install FastHTML and build a first interactive page

Installation is a single pip command. The README gives it directly, and the package name is python-fasthtml, not fasthtml.

pip install python-fasthtml

After that, the README's minimal app is a file called main.py. Create it with the content below. The import pulls in the element classes and the fast_app and serve helpers; the route returns a Div holding a P whose hx_get attribute points at a second route.

from fasthtml.common import *

app,rt = fast_app()

@rt('/')
def get(): return Div(P('Hello World!'), hx_get="/change")

serve()

Run it with python main.py. According to the README, the process prints a link to http://localhost:5001, and visiting that address shows a page with the text "Hello World!".

Adding the interaction is a second function in the same file. This route answers the request that the hx_get attribute triggers, and its return value replaces the original paragraph.

@rt('/change')
def get(): return P('Nice to be here!')

Restart the process, click the text, and the paragraph is swapped for the new one. That is the smallest complete FastHTML app: two routes, one HTMX attribute, no template files and no build step.

One practical note the README raises: because FastHTML is newer than most LLMs, assistants such as Cursor, ChatGPT, Claude and Copilot will not give useful answers about it from their training data alone. The project publishes an LLM-friendly context file at https://www.fastht.ml/docs/llms-ctx.txt, generated from its llms.txt, which you can attach to an AI helper. In Cursor the README suggests typing @doc, choosing Add new doc, and supplying that link.

Where FastHTML gets thin: documentation gaps and the alpha label

The README is unusually candid about the state of the project. It states that the capabilities of FastHTML are "vast and growing, and not all the features and patterns have been documented yet", and it advises being prepared to invest time studying and modifying source code, including the main repository's notebooks and the separate fasthtml-example repository. That is not marketing hedging; it is a description of where answers live.

The consequence is concrete. If you need a feature that the docs site does not cover, your options are the notebooks in the repository, the examples repository, the gallery, or the Discord. There is no API reference that the README points to as complete. For a solo developer exploring an idea, that is tolerable. For a team that needs to onboard three engineers next month, it is a real cost, because the onboarding path runs through Jupyter notebooks rather than a stable reference.

The Alpha classifier in pyproject.toml reinforces the same point from a different direction. Version 0.14.13 shipped on 2026-09-03, after 0.14.12 on 2026-08-19 and 0.14.11 on 2026-07-31, so releases are frequent. Frequent minor releases in the 0.x range mean you should expect to read the CHANGELOG.md before upgrading rather than assuming compatibility. The repository also carries an htmxv4_migration directory, which signals that a migration between HTMX major versions has already been a project concern.

There is one more constraint worth naming: the Python requirement is >=3.10, declared in pyproject.toml. If your deployment target is pinned to an older interpreter, that is a hard boundary, not a preference.

FastHTML compared with FastAPI, Flask and Streamlit

The comparison that matters most is with FastAPI, because both are Python and both sit on ASGI machinery. The difference is what a route returns. FastAPI is built around typed request and response models, so a handler typically returns data that is serialised to JSON, and the front end is a separate concern that consumes it. FastHTML handlers return HTML elements, and the client is HTMX swapping fragments. If your consumers are mobile apps or third-party services, FastAPI is the correct shape and FastHTML is the wrong one, because FastHTML's output is markup meant for a browser.

Against Flask, the split is about templating and interactivity. Flask routes commonly render Jinja templates from separate files. FastHTML builds markup in Python, so the element tree is ordinary code you can loop over, pass around and test. The README also notes that FastHTML apps are just Python, so the full language and ecosystem are available. Whether that is better depends on who edits the markup: designers who expect template files will not find them here.

Streamlit solves a different problem. It is aimed at quickly turning data scripts into an app, and it owns the layout and rerun model. FastHTML gives you the HTML and HTTP directly, which means more control over the page and more decisions to make. For an internal dashboard thrown together in an afternoon, Streamlit's constraints are a feature. For a page with specific markup and interaction requirements, FastHTML's 1:1 mapping is the advantage.

The README itself points elsewhere for people who want only the HTML-generation part: fastcore.xml.FT, htpy, and the Clojure-style hiccup family. It also lists htmgo for Go developers who want the same HTMX-based approach in a compiled binary. Those are honest pointers to adjacent tools rather than competitors being dismissed.

Licence, packaging and the cost of keeping up

FastHTML is licensed under Apache-2.0, declared both in the repository and in the license field of pyproject.toml. That is a permissive licence with an explicit patent grant, which matters if you are embedding the library in a commercial product. It is not a copyleft licence, so it does not impose source-disclosure obligations on your application. This is a description of what the files declare, not legal advice; if the licence terms affect a product decision, have someone qualified read the LICENSE file.

The upgrade cost is mostly a function of release cadence. Three releases landed between 2026-07-31 and 2026-09-03, and the package is still classified as Alpha. The repository ships a CHANGELOG.md at the top level, so the practical routine is to read that file before bumping the pin, and to run the tests in the tests directory against your own app if you have them. Because the framework is a thin layer over starlette and uvicorn, some breakage will surface as ASGI-level behaviour rather than as a FastHTML API change, which can make the cause less obvious.

There is no component library to install yet. The README says that the project hopes to add component libraries installable via pip "in the near future", so today the reusable pieces come from the gallery, the examples repository, or your own code. Budget for writing the components you would otherwise import.

Deployment has a small amount of built-in help: pyproject.toml declares two console scripts, fh_railway_link and fh_railway_deploy, which map to functions in fasthtml.cli. Those are the only deployment entry points named in the project files.

Editorial conclusion

FastHTML suits Python developers who want interactive pages without a JavaScript build step, and who are willing to read source notebooks when the docs run out. It is a poor fit for teams that need stable, fully documented APIs or a large third-party component ecosystem, since the README states that not all features and patterns have been documented yet. Before adopting it, verify the current version, the Python requirement of >=3.10, and whether the /llms-ctx.txt context file covers the features your app depends on.

Frequently asked questions

Official sources

1. AnswerDotAI/fasthtml on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases