FastAPI "uvicorn: command not found" in CI

By Daniel Zoghalchali·Latchkey

The shell could not find a uvicorn executable. Either uvicorn was never installed into the active interpreter, or it lives in a venv the step did not activate, so its console script is not on PATH.

What this error means

A step that runs uvicorn app.main:app fails with "uvicorn: command not found" and exit code 127, even though python --version works.

/home/runner/work/_temp/script.sh: line 1: uvicorn: command not found
Error: Process completed with exit code 127.

Diagnose it: which interpreter and which environment?

which -a python python3 pip
python -c "import sys; print(sys.executable); print(sys.version)"
python -c "import sys; [print(p) for p in sys.path]"
pip list 2>/dev/null | head -20

Common causes

uvicorn is not a declared dependency

The install step brought in FastAPI but not uvicorn, so no uvicorn script exists on the runner.

A venv holding uvicorn was not activated

uvicorn is installed inside a virtual environment that the current step did not activate, so the launcher is not on PATH.

How to fix it

Install uvicorn and run it as a module

Add uvicorn to your dependencies and invoke it through the interpreter so PATH is never the issue.

python -m pip install "uvicorn[standard]"
python -m uvicorn app.main:app --host 0.0.0.0 --port 8000

Activate the venv that holds uvicorn

1. Confirm uvicorn is installed with python -m pip show uvicorn.
2. Activate the venv in the same step before calling uvicorn.
3. Prefer python -m uvicorn over the bare console script.

. .venv/bin/activate
python -m uvicorn app.main:app

How to prevent it

• Declare uvicorn[standard] in your requirements or pyproject dependencies.
• Call python -m uvicorn so PATH lookup never fails.
• Activate the correct venv in every step that launches the server.

Frequently asked questions

Related guides

References

• Python documentation
• pip documentation
• GitHub Actions documentation