Skip to content

Troubleshooting · By Rivtor · Updated

Fix Python ModuleNotFoundError after deployment

Check whether the missing name is an external distribution, local package or native-library dependency. Install the runtime manifest into the interpreter that starts the service and verify the deployed working directory and build context before changing import paths.

See the Rivtor deployment workflow →

Identify which kind of module is missing

An import name is not always the package-manager distribution name. A module can also be your own package omitted from the image, a file with different case, or a dependency that fails to load a native library. Read the full traceback and locate the first failing import.

Missing inputCheck
Third-party moduleCorrect distribution in runtime dependencies
Local packageIncluded files and importable package layout
Optional dependencyExtra installed for the feature actually used
Native libraryRuntime image packages and architecture

Avoid installing a random package merely because its name resembles the error. Confirm the dependency through the application’s documentation or manifest.

Compare interpreter and environment

From a disposable runtime matching the service, inspect the interpreter and installation:

python -c "import sys; print(sys.executable)"
python -m pip --version

Using python -m pip helps tie installation to the selected interpreter. A package installed in a developer’s virtual environment is not necessarily installed in the production image. A build stage can contain tools that the final runtime stage intentionally omits.

Fix the packaging boundary

Commit the required runtime dependency through the project’s existing lock workflow. Include local package source or built artifacts in the build context. Check the service root and whether an ignore file accidentally excludes needed code.

For Rivtor, review framework detection and custom Dockerfiles. A structured missing-module error should lead to the relevant service manifest, not an unrelated root-level install. Do not hardcode filesystem paths that only exist on the development machine.

Verify a clean start and a real request

Build without local dependency directories, start the production command and execute a synthetic route that imports the affected code. Lazy imports can make health succeed while the first real request still fails. Keep development-only and runtime dependencies deliberate, and record the corrected module/package relationship for the next deployment.

References