FixingModuleNotFoundError: No module named 'waitress'

What causes ModuleNotFoundError waitress in a python flask app, and how to fix it properly for production deployment.

Fixing "ModuleNotFoundError: No module named 'waitress'"

If you're seeing this in your logs:

ModuleNotFoundError: No module named 'waitress'

right after trying to serve a Flask app in production, the cause is almost always exactly what the message says — Waitress genuinely isn't installed in your environment. Here's why that happens even when you thought you'd set up production serving, and the couple of ways to actually fix it.

Table of Contents

1. What Waitress Is and Why You'd Need It
2. Why It's Missing Even After You "Installed Everything"
3. The Direct Fix
4. The StayPresent-Specific Fix
5. Verifying the Fix Actually Worked
6. A Silent Variant of This Problem
7. Full Example
8. FAQs
9. Conclusion

What Waitress Is and Why You'd Need It

Waitress is a pure-Python, production-grade WSGI server — an alternative to Flask's own built-in development server, which explicitly warns it isn't meant for production traffic. Code that calls from waitress import serve needs the waitress package actually present in the running environment; if it isn't, you get exactly the ModuleNotFoundError above the moment that import line executes.

Why It's Missing Even After You "Installed Everything"

This trips people up constantly because it often looks like it should be installed. A few common causes:

• waitress was installed locally, but never added to requirements.txt — so your deployment platform's fresh build never installs it.
• A virtual environment mismatch — waitress is installed in one venv, but the app actually runs from a different one (or the system Python) that doesn't have it.
• An optional-dependency package (like StayPresent) was installed without its "prod" extra, so Waitress was never pulled in as a dependency in the first place.

The Direct Fix

If you're using Waitress directly:

pip install waitress

And make sure it's actually captured in your dependency file:

# requirements.txt
waitress

The StayPresent-Specific Fix

If the ModuleNotFoundError is coming from a StayPresent-based deployment, the fix is installing the prod extra specifically, rather than waitress on its own:

pip install staypresent[prod]

# requirements.txt
staypresent[prod]

Note that StayPresent itself never raises this error directly — it's designed to gracefully fall back to Flask's own development server (with a one-time warning) if Waitress isn't available, rather than crashing. If you're seeing a bare ModuleNotFoundError: No module named 'waitress', it's most likely coming from your own code importing Waitress directly somewhere, separate from StayPresent's internal handling.

Verifying the Fix Actually Worked

After redeploying, confirm Waitress is actually being used rather than assumed:

import logging

logging.getLogger("staypresent").setLevel(logging.INFO)

The startup log line from the "staypresent" logger states explicitly which server backend it bound with — this is the fastest way to confirm the fix took effect rather than guessing.

A Silent Variant of This Problem

There's a quieter version of this same underlying issue: Waitress is installed, but something about the environment (a build cache, a stale lockfile, a platform-specific wheel issue) means it isn't actually importable at runtime, even though pip install reported success during the build step. If reinstalling and confirming requirements.txt doesn't resolve it, clearing your platform's build cache and forcing a fresh install is usually the next step.

Full Example

import os
import staypresent

staypresent.web.json({"status": "running"})

staypresent.run(
    "bot.py",
    port=int(os.getenv("PORT", 8080)),
)

# requirements.txt
staypresent[prod]

pip install -r requirements.txt

FAQs

Does StayPresent crash if Waitress is missing?
No — it falls back to Flask's built-in development server automatically, logging a one-time warning rather than raising an error.

Why isn't Waitress just a hard dependency of StayPresent?
Making it optional keeps the base install lightweight for local development or testing, where the dev server is perfectly adequate — the prod extra exists specifically for when you actually need production-grade serving.

Can I use Gunicorn instead of Waitress?
StayPresent specifically uses Waitress internally since it's cross-platform (including Windows); if you need Gunicorn for a separate part of your stack, that's a different, unrelated setup from StayPresent's own server.

Conclusion

ModuleNotFoundError: No module named 'waitress' is almost always a straightforward dependency-installation gap — either Waitress itself, or (if you're using StayPresent) the prod extra, missing from what actually gets installed at deploy time. Fixing your requirements.txt and confirming the fix through StayPresent's own startup log resolves it in nearly every case.

pip install staypresent[prod]