gramps-web-api Throws "ModuleNotFoundError: No module named 'waitress'" After Executing "Executing task: python3 -O -m gramps_webapi run", etc.

[odiouschris]

Based on grampsweb.org/development/backend/setup/, what more do I need?

Operating System: Ubuntu 24.04.3 LTS

Docker Version

4.59.0 (217644)

Engine: 29.2.0

Compose: v5.0.2

Credential Helper: v0.9.5

Kubernetes: v1.34.1

VS Code Version: 1.109.0
Commit: bdd88df003631aaa0bcbe057cb0a940b80a476fa
Date: 2026-02-04T02:01:38.288Z
Electron: 39.3.0
ElectronBuildId: 13168319
Chromium: 142.0.7444.265
Node.js: 22.21.1
V8: 14.2.231.22-electron.0
OS: Linux x64 6.17.0-14-generic

Installation
Identifier
ms-vscode-remote.remote-containers
Version
0.442.0
Last Updated
9 hours ago
Size
7.21MB
Cache
4.43KB

• Executing task: python3 -O -m gramps_webapi run --port 5555 --host 0.0.0.0

Traceback (most recent call last):
File "", line 198, in _run_module_as_main
File "", line 88, in _run_code
File "/home/human/Documents/gramps-web-api/gramps_webapi/main.py", line 34, in
import waitress # type: ignore
^^^^^^^^^^^^^^^
ModuleNotFoundError: No module named 'waitress'

• The terminal process "/usr/bin/bash '-c', 'python3 -O -m gramps_webapi run --port 5555 --host 0.0.0.0'" terminated with exit code: 1.
• Terminal will be reused by tasks, press any key to close it.

[DavidMStraub]

That's not what that doc pages says.

And we can't help if you don't document your full steps.

waitress is a dependency in pyporject.toml.

[odiouschris]

That's not what that doc pages says.

Agreed. The documentation at https://www.grampsweb.org/development/backend/setup/, (accessed 2026-02-08) includes no information helpful in this case, so I thought I'd ask.

Full steps: I downloaded Ubuntu and Docker, etc (kindly read above), between 2026-02-06 and 2026-02-07. I won't document the full steps involved in installing Ubuntu, Docker, etc., because although that is what you asked, I suspect that will not produce a result. Disabuse me if I am incorrect.

The steps I followed (excepting the linux terminal commands to install (see above)) are documented here:

https://www.grampsweb.org/development/backend/setup/

Do you have a specific start for "full steps" (e.g.: Open VS Code, select "Clone Repository", select Documents as destination folder, wait whist repo clones, select "Reopen in Container" VS Code prompt, etc)?

[DavidMStraub]

Ok I think I know what the problem is. You did not follow this instruction:

Wait for the dev container to build and start. This may take a few minutes, especially the first time.
After the Dev Container build is successful, the command will return:
Successfully installed gramps-webapi-x.x.x.

but instead started the task prematurely.

[odiouschris]

Indeed I did (I hope).

I contributed the referenced instruction based on your reply to gramps-project/gramps-web-docs#69 (comment).

[DavidMStraub]

I claim that the error ModuleNotFoundError: No module named 'waitress' cannot happen if Successfully installed gramps-webapi-x.x.x completed.

[odiouschris]

From my experience attempting to run gramps-web-api, and subsequently, gramps-web on Windows 11 and Ubuntu 24.04.4, I observe:

On an Internet connection of ~3Mbps, the Docker build command (I will not name it) can take more than 24 hours,
1b. "Rebuild", "Reopen", and "Rebuild without cache" are very different commands,
if one has not "messed" with the main [forked] branch, the command (1) can be fault-tolerant (i.e. if error, repeat the previous step),
3b. there may be a problem if the database isn't loaded correctly the first time (I NEVER want to test that again winky face), and
even though this is an "offline" project that utilizes containers in Docker, it is advisable to have >3Mbps connectivity to clone, build and serve both projects.