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 input | Check |
|---|---|
| Third-party module | Correct distribution in runtime dependencies |
| Local package | Included files and importable package layout |
| Optional dependency | Extra installed for the feature actually used |
| Native library | Runtime 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.