What is the --factory flag in Uvicorn and when is it useful?

The --factory flag tells Uvicorn to treat the specified application path as a factory function - a callable that takes no arguments and returns an ASGI application - rather than as the application itself.

# Without --factory: APP is the application object directly
uvicorn main:app

# With --factory: create_app() is called to produce the ASGI app
uvicorn main:create_app --factory

# Example factory function:
# main.py
def create_app():
    from fastapi import FastAPI
    app = FastAPI()

    @app.get("/")
    def root():
        return {"status": "ok"}

    return app

# The factory is called with no arguments and must return the ASGI app

# Programmatic equivalent:
uvicorn.run("main:create_app", factory=True, port=8000)

# Why use a factory?
# - Deferred initialisation (resources created only when workers start)
# - Different config per environment (testing vs production)
# - Integration with dependency injection frameworks
# - Worker-level initialisation (each Gunicorn worker calls the factory separately)

Key use case - Gunicorn + factory: when using Gunicorn with multiple workers, each worker process calls the factory independently. This is important for resources that must be created per-process (like database connection pools) - a factory guarantees each worker initialises its own pool rather than sharing one created before forking.

Invest now in Acorns!!! 🚀
Join Acorns and get your $5 bonus!

Acorns is a micro-investing app that automatically invests your "spare change" from daily purchases into diversified, expert-built portfolios of ETFs. It is designed for beginners, allowing you to start investing with as little as $5. The service automates saving and investing. Disclosure: I may receive a referral bonus.

Invest now!!! Get Free equity stock (US, UK only)!

Use Robinhood app to invest in stocks. It is safe and secure. Use the Referral link to claim your free stock when you sign up!.

The Robinhood app makes it easy to trade stocks, crypto and more.

Webull! Receive free stock by signing up using the link: Webull signup.