uvicorn

Run Python web app

$ uvicorn [import.path:app_object]

$ uvicorn --host [localhost] --port [8080] [import.path:app_object]

$ uvicorn --reload [import.path:app_object]

$ uvicorn --workers [4] [import.path:app_object]

$ uvicorn --ssl-certfile [cert.pem] --ssl-keyfile [key.pem] [import.path:app_object]

uvicorn <module:app_object> [OPTIONS]

Examples:
uvicorn main:app
uvicorn main:app --reload --host 0.0.0.0 --port 8000

<module:app_object>
    The path to your ASGI application. For example, main:app refers to an ASGI application object named 'app' inside a file named 'main.py'.

--host <host>
    The host address to bind to. Defaults to 127.0.0.1 (localhost). Use 0.0.0.0 to listen on all available network interfaces.

--port <port>
    The port number to bind to. Defaults to 8000.

--reload
    Enables auto-reloading of the server when source code changes are detected. Primarily for development use.

--workers <num>
    The number of worker processes to run. Defaults to 1. Useful for leveraging multiple CPU cores or improving concurrency for CPU-bound tasks.

--log-level <level>
    Sets the logging level (e.g., info, debug, warning, error, critical). Defaults to info.

--uds <path>
    Binds to a Unix domain socket at the specified path instead of a TCP host/port. E.g., --uds /tmp/uvicorn.sock.

--loop <loop_type>
    Specifies the event loop implementation to use (e.g., auto, uvloop, asyncio). Defaults to auto, which attempts to use uvloop if available.

--app-dir <dir>
    Changes the current working directory before loading the application module. Useful for managing Python's module search path.

--ssl-keyfile <path>
    Path to the SSL key file (PEM format) for enabling HTTPS.

--ssl-certfile <path>
    Path to the SSL certificate file (PEM format) for enabling HTTPS.

Uvicorn is a lightning-fast ASGI (Asynchronous Server Gateway Interface) web server for Python. It's built on uvloop and httptools, making it exceptionally performant for handling asynchronous I/O.

Designed to run modern Python web applications, especially those built with frameworks like FastAPI and Starlette, Uvicorn efficiently translates HTTP requests into ASGI calls and manages the application's lifecycle. It supports both HTTP/1.1 and WebSockets, enabling robust and scalable deployments for high-concurrency environments. Its simplicity, speed, and adherence to the ASGI standard have established it as a popular choice for deploying asynchronous Python web APIs and services.

• Development vs. Production: The --reload option is strictly for development and should not be used in production environments due to potential race conditions and performance overhead.
• Worker Usage: While --workers increases concurrency, for predominantly I/O-bound asynchronous applications, a single worker is often sufficient due to asyncio's non-blocking nature. Multiple workers are more beneficial for CPU-bound tasks or when managing multiple concurrent requests for I/O bound applications in a multi-core environment.
• WSGI Compatibility: Uvicorn is an ASGI server. It does not directly serve traditional WSGI applications without a compatibility layer or wrapper.

For production deployments, Uvicorn is commonly run behind a robust process manager like Gunicorn. This 'Gunicorn + Uvicorn Worker' setup (e.g., gunicorn -k uvicorn.workers.UvicornWorker) provides essential features such as process supervision, graceful restarts, and load balancing across multiple Uvicorn worker processes, which Uvicorn itself does not provide as a standalone server.

Uvicorn's core function is to implement the Asynchronous Server Gateway Interface (ASGI) specification. ASGI is a successor to the older WSGI specification, designed specifically to accommodate Python's asynchronous features, WebSockets, and long-lived network connections, making it suitable for modern, real-time web applications.

Uvicorn emerged around 2018-2019, driven by the need for high-performance asynchronous web servers in Python following the introduction of the ASGI specification. Developed primarily by Tom Christie, it quickly became the de-facto server for new asynchronous Python web frameworks like Starlette and FastAPI, which leverage Python's async/await syntax. Its focus on speed, stability, and adherence to the ASGI standard helped solidify its position as a key component in modern Python web development.

gunicorn(1), fastapi(1), starlette(1), hypercorn(1)