How to Set Response Headers in FastAPI Quickly and Easily

In FastAPI, you can set response headers by returning a Response object with custom headers or by using the Response parameter in your path operation function to modify headers directly. This allows you to add any HTTP headers before sending the response to the client.

Syntax

There are two common ways to set response headers in FastAPI:

• Return a Response object: Create a Response instance with your content and a headers dictionary.
• Use Response parameter: Accept a Response parameter in your path function and set headers on it directly.

Both methods let you control HTTP headers sent back to the client.

python

from fastapi import FastAPI, Response

app = FastAPI()

# Method 1: Return Response with headers
@app.get("/method1")
def method1():
    headers = {"X-Custom-Header": "Value1"}
    return Response(content="Hello from method1", headers=headers, media_type="text/plain")

# Method 2: Use Response parameter
@app.get("/method2")
def method2(response: Response):
    response.headers["X-Custom-Header"] = "Value2"
    return "Hello from method2"

Example

This example shows how to set a custom header X-Powered-By in two ways: by returning a Response object and by modifying the Response parameter.

python

from fastapi import FastAPI, Response

app = FastAPI()

@app.get("/header1")
def header1():
    headers = {"X-Powered-By": "FastAPI"}
    return Response(content="Response with header1", headers=headers, media_type="text/plain")

@app.get("/header2")
def header2(response: Response):
    response.headers["X-Powered-By"] = "FastAPI"
    return "Response with header2"

Output

When you call /header1 or /header2, the HTTP response includes the header:
X-Powered-By: FastAPI

Common Pitfalls

• Setting headers after returning a response does not work; headers must be set before the response is sent.
• Using return {} or plain data without a Response object won't let you add headers directly.
• For JSON responses, use JSONResponse if you want to set headers and return JSON content.

python

from fastapi import FastAPI, Response
from fastapi.responses import JSONResponse

app = FastAPI()

# Wrong: headers set after return (won't work)
@app.get("/wrong")
def wrong(response: Response):
    response.headers["X-Wrong"] = "NoEffect"
    result = {"message": "Hello"}
    return result

# Right: use JSONResponse to set headers
@app.get("/right")
def right():
    headers = {"X-Right": "Works"}
    return JSONResponse(content={"message": "Hello"}, headers=headers)

Quick Reference

Summary tips for setting response headers in FastAPI:

• Use Response or JSONResponse to return content with headers.
• Or accept a Response parameter and set headers on it before returning.
• Headers must be set before returning the response.
• For JSON data, prefer JSONResponse to combine JSON content and headers.

Key Takeaways

Set response headers in FastAPI by returning a Response object with headers or modifying the Response parameter.

Headers must be set before the response is returned to the client.

Use JSONResponse to set headers when returning JSON content.

Directly returning dict or data does not allow header modification without Response objects.

Both methods let you add any custom HTTP headers easily.