FastapiHow-ToBeginner · 3 min read

How to Use HTMLResponse in FastAPI: Simple Guide

In FastAPI, use HTMLResponse from fastapi.responses to return HTML content directly from your endpoint. Simply import HTMLResponse and set it as the response_class in your route decorator or return it explicitly from your function.

📐

Syntax

The HTMLResponse class is imported from fastapi.responses. You can use it in two main ways:

Set response_class=HTMLResponse in the route decorator to tell FastAPI to treat the return value as HTML.
Return an HTMLResponse object directly from your endpoint function.

This allows you to send raw HTML strings as the response body.

python

from fastapi import FastAPI
from fastapi.responses import HTMLResponse

app = FastAPI()

@app.get("/", response_class=HTMLResponse)
async def read_root():
    return "<h1>Hello, FastAPI with HTMLResponse!</h1>"

💻

Example

This example shows a FastAPI app that returns a simple HTML page using HTMLResponse. The route decorator sets response_class=HTMLResponse, so the returned string is sent as HTML content.

python

from fastapi import FastAPI
from fastapi.responses import HTMLResponse

app = FastAPI()

@app.get("/", response_class=HTMLResponse)
async def home():
    html_content = """
    <html>
        <head>
            <title>FastAPI HTMLResponse Example</title>
        </head>
        <body>
            <h1>Welcome to FastAPI!</h1>
            <p>This page is served as HTML.</p>
        </body>
    </html>
    """
    return html_content

Output

HTTP/1.1 200 OK content-type: text/html; charset=utf-8 <html> <head> <title>FastAPI HTMLResponse Example</title> </head> <body> <h1>Welcome to FastAPI!</h1> <p>This page is served as HTML.</p> </body> </html>

⚠️

Common Pitfalls

Common mistakes when using HTMLResponse include:

Not setting response_class=HTMLResponse in the decorator and returning a string, which FastAPI treats as JSON by default.
Returning plain strings without wrapping them in HTMLResponse when not using response_class, causing incorrect content type.
Forgetting to import HTMLResponse from fastapi.responses.

Always ensure the response is correctly marked as HTML to avoid browser display issues.

python

from fastapi import FastAPI
from fastapi.responses import HTMLResponse

app = FastAPI()

# Wrong: returns string but no HTMLResponse set, defaults to JSON
@app.get("/wrong")
async def wrong():
    return "<h1>This will be JSON, not HTML</h1>"

# Right: explicitly return HTMLResponse
@app.get("/right")
async def right():
    return HTMLResponse(content="<h1>This is HTML!</h1>")

📊

Quick Reference

Usage	Description
response_class=HTMLResponse	Set in route decorator to return HTML from string
return HTMLResponse(content=html_string)	Return HTMLResponse object directly
Import	from fastapi.responses import HTMLResponse
Content-Type	Automatically set to text/html; charset=utf-8
Use case	Serve raw HTML pages or fragments

✅

Key Takeaways

Import HTMLResponse from fastapi.responses to send HTML content.

Use response_class=HTMLResponse in route decorators to return HTML strings.

Alternatively, return an HTMLResponse object directly from your endpoint.

Without HTMLResponse, FastAPI treats strings as JSON by default.

HTMLResponse sets the correct content-type header for browsers.