Install Uvicorn in Python Guide

Uvicorn is a fast ASGI server for Python. It helps you run async web applications. This guide shows you how to install Uvicorn easily.

What is Uvicorn?

Uvicorn is a lightning-fast ASGI server implementation. It uses uvloop and httptools for high performance. Many modern Python frameworks like FastAPI and Starlette use it.

Uvicorn supports HTTP/1.1 and WebSockets. It is built on top of the asyncio event loop. This makes it perfect for async Python applications.

Prerequisites

Before you install Uvicorn, you need Python 3.7 or newer. Check your Python version with this command:

python --version

You also need pip, the Python package manager. Verify pip is installed:

pip --version

If you don't have pip, install it first. Download it from the official Python website.

Install Uvicorn with pip

The easiest way to install Uvicorn is using pip. Open your terminal or command prompt. Run this command:

pip install uvicorn

This installs Uvicorn and its core dependencies. You will see output like this:

Collecting uvicorn
  Downloading uvicorn-0.29.0-py3-none-any.whl (60 kB)
     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 60.0/60.0 kB 1.2 MB/s eta 0:00:00
Installing collected packages: uvicorn
Successfully installed uvicorn-0.29.0

If you want extra features, use the standard extra. This includes uvloop and httptools for better performance:

pip install uvicorn[standard]

Install Uvicorn in a Virtual Environment

It's a best practice to use a virtual environment. This keeps your project dependencies isolated. First, create a virtual environment:

python -m venv myenv

Activate it. On Windows:

myenv\Scripts\activate

On macOS or Linux:

source myenv/bin/activate

Now install Uvicorn inside the virtual environment:

pip install uvicorn

This keeps your global Python clean. You can also use a requirements.txt file to track dependencies.

Verify the Installation

Check if Uvicorn installed correctly. Run this command:

uvicorn --version

You should see output like:

Uvicorn running on 0.29.0 (CPython 3.12.0)

If you see the version number, the installation succeeded. Now you can start using Uvicorn.

Run Your First Uvicorn App

Create a simple ASGI app. Make a file named app.py with this code:

# app.py - Simple ASGI application
async def app(scope, receive, send):
    assert scope['type'] == 'http'

    await send({
        'type': 'http.response.start',
        'status': 200,
        'headers': [
            (b'content-type', b'text/plain'),
        ],
    })

    await send({
        'type': 'http.response.body',
        'body': b'Hello, Uvicorn!',
    })

Save the file. Then run Uvicorn from the terminal:

uvicorn app:app

Here, app:app means the file app.py and the ASGI callable app. You will see output:

INFO:     Started server process [12345]
INFO:     Waiting for application startup.
INFO:     ASGI 'lifespan' protocol appears unsupported.
INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

Open your browser and go to http://127.0.0.1:8000. You will see "Hello, Uvicorn!". Press CTRL+C to stop the server.

Common Installation Issues

Sometimes you might see a PermissionError. This happens when you try to install globally without admin rights. Use the --user flag:

pip install --user uvicorn

Another issue is a missing compiler for uvloop. If you see build errors, install the standard version without extras:

pip install uvicorn --no-binary :all:

Or just use the minimal install. It works fine for most cases.

Using Uvicorn with FastAPI

Uvicorn works great with FastAPI. Install FastAPI first:

pip install fastapi

Create a FastAPI app in main.py:

# main.py - FastAPI application
from fastapi import FastAPI

app = FastAPI()

@app.get("/")
async def read_root():
    return {"message": "Hello from FastAPI and Uvicorn!"}

Run it with Uvicorn:

uvicorn main:app --reload

The --reload flag enables auto-reload during development. Visit http://127.0.0.1:8000 to see the JSON response.

Uvicorn Command-Line Options

Uvicorn has many useful options. Change the host and port with --host and --port:

uvicorn app:app --host 0.0.0.0 --port 8080

Use --workers to run multiple worker processes:

uvicorn app:app --workers 4

Enable logging with --log-level:

uvicorn app:app --log-level debug

These options give you fine control over your server.

Uninstall Uvicorn

If you need to remove Uvicorn, use pip:

pip uninstall uvicorn

Confirm the removal when prompted. This cleans your environment.

Conclusion

Installing Uvicorn in Python is simple. Use pip install uvicorn and you are ready. Always use a virtual environment for clean dependency management. Uvicorn powers modern async web apps with speed and reliability. Start with a basic ASGI app, then explore frameworks like FastAPI. With Uvicorn, you can build high-performance Python web services today.