How to use the command 'uvicorn' (with examples)

Uvicorn is a fast, lightweight ASGI server implementation that is ideal for serving asynchronous web applications built with Python. By leveraging Python’s asynchronous capabilities, Uvicorn allows developers to handle a large number of requests simultaneously, making it a popular choice for modern web applications that require high performance and scalability. This article explores various use cases of the uvicorn command, illustrating how it can be utilized to run and manage Python web apps efficiently.

Use case 1: Run Python web app

Code:

uvicorn import.path:app_object

Motivation: Running a Python web app using Uvicorn is one of its most straightforward use cases. This allows developers to quickly start serving their ASGI-compatible applications during development or in production environments.

Explanation:

• import.path:app_object: This is the target application that Uvicorn will serve. The import.path refers to the Python module where your app is located, and app_object is the ASGI application instance within that module. Uvicorn will start a server instance to serve this application.

Example output:

When the command is executed, you might see output similar to the following:

INFO:     Started server process [12345]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

This output indicates that the server process has started, and your application is available at the specified address.

Use case 2: Listen on port 8080 on localhost

Code:

uvicorn --host localhost --port 8080 import.path:app_object

Motivation: By default, Uvicorn runs on 127.0.0.1:8000, which might not always be the desired setup, especially if you need to specify the host or port due to network configurations or testing requirements. This command is useful for developers who want specific control over the networking details of their application.

Explanation:

• --host localhost: Specifies that the server should bind to the localhost interface. This limits accessibility to the local machine, which can be important for security during development.
• --port 8080: Changes the port number the application listens on. This is useful if port 8000 is occupied or if you are required to use a specific port due to organizational policies.

Example output:

Executing this command starts the server and provides output like:

INFO:     Started server process [12345]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://localhost:8080 (Press CTRL+C to quit)

Use case 3: Turn on live reload

Code:

uvicorn --reload import.path:app_object

Motivation: During development, it’s common to make frequent changes to application code. The --reload option allows the server to automatically restart whenever code changes are detected, significantly enhancing the development workflow by eliminating the need to manually restart the server.

Explanation:

• --reload: Enables live reload mode. Uvicorn watches the code files for changes and automatically restarts the server to reflect those changes instantaneously. This is particularly helpful in iterative development environments where changes need to be tested quickly.

Example output:

With live reload, the output looks like this:

INFO:     Started server process [12345]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
INFO:     Watching for file changes with StatReload

This output includes confirmation that Uvicorn is monitoring file changes.

Use case 4: Use 4 worker processes for handling requests

Code:

uvicorn --workers 4 import.path:app_object

Motivation: To handle a higher load of incoming requests, Uvicorn can spawn multiple worker processes. This is vital for applications needing to serve a large number of users simultaneously, particularly in production environments.

Explanation:

• --workers 4: Configures the server to start with four separate worker processes, each capable of handling incoming requests. This increases the server’s capacity to process requests concurrently, improving the performance of resource-intensive applications.

Example output:

Upon starting with multiple workers, you might see:

INFO:     Started parent process [12345]
INFO:     Started server process [23456]
INFO:     Started server process [23457]
INFO:     Started server process [23458]
INFO:     Started server process [23459]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

This shows each worker being initialized to handle requests independently.

Use case 5: Run app over HTTPS

Code:

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

Motivation: For applications requiring secure communication, running the server over HTTPS ensures that data transmitted between the client and server is encrypted, protecting against man-in-the-middle attacks.

Explanation:

• --ssl-certfile cert.pem: Specifies the path to the SSL certificate file. An SSL certificate authenticates the identity of the website and enables an encrypted connection.
• --ssl-keyfile key.pem: Provides the path to the SSL key file, which is used as a part of the encryption process during secure communications.

Example output:

Upon secure startup, you might see:

INFO:     Started server process [12345]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on https://127.0.0.1:8000 (Press CTRL+C to quit)

The URL shown here begins with https://, indicating that the server is running with SSL enabled.

Conclusion:

In this article, we’ve explored multiple use cases of the uvicorn command, showing its flexibility and power in serving asynchronous Python applications. From simple local development setups to more complex multi-worker and secure deployments, Uvicorn offers a breadth of options to cater to different development and production environments. Understanding these use cases can help developers optimize their workflow and application performance.