Activation in a terminal does not configure a service
A developer can activate a virtual environment and run an application successfully while a process manager launches a different Python interpreter. The service then reports missing packages or imports an unexpected version. The relevant environment is the one used by the running process, not the shell that happened to prepare the deployment.
A virtual environment isolates an interpreter's package installation context. It is not a portable archive that should automatically be copied between arbitrary operating systems, interpreter versions or filesystem paths. Reconstruct the release environment from declared dependencies and a known interpreter.
Setup: record executable identity
Inventory the intended Python version, operating system, dependency source and production launch command. In an isolated release directory, create a new environment and install from the project's reviewed dependency specification. Record the actual interpreter path and package metadata used for the build.
The Python venv documentation notes that activation is optional when invoking the environment's interpreter directly. This is useful for process managers: an explicit executable path is clearer than relying on an interactive shell activation step that may never run for a service. Keep secrets outside the artifact and configure their delivery independently of package installation.
Illustrative incident: the service cannot import a package
An illustrative API starts correctly from a developer's terminal. Under the production supervisor, it fails on an import because the service command references a system interpreter. Reinstalling packages in the developer's activated environment changes nothing about that command. This is a teaching example, not a reported client incident.
Compare the interpreter and module locations from the successful command and the supervised process. Use a small diagnostic that reports paths and versions without printing environment secrets. Preserve the failing launch configuration before editing it.
Troubleshooting: compare installation and execution
| Symptom | Evidence | Investigation |
|---|---|---|
| Package installed but import fails | Interpreter used by install and service | Were dependencies installed into another environment? |
| Works on one server only | Python version and dependency resolution | Is the release specification reproducible? |
| Copied environment contains broken scripts | Embedded paths and source platform | Should the environment be recreated locally? |
| Native extension fails to load | Platform, ABI and system libraries | Does the artifact match the target runtime? |
Avoid solving the problem with a global administrator-level package install. That can affect unrelated services and conceal the missing environment contract. Also distinguish a package import name from its distribution name when reviewing dependency metadata.
Corrective action and release construction
Use the environment's explicit interpreter for installation checks, migrations and service startup. Rebuild the environment in the candidate release directory rather than modifying the currently serving environment in place. Pin dependencies through the project's supported tooling and retain the lock or resolved specification used by that release.
For native dependencies, verify the build platform and required system libraries. Reproducible Python package versions do not automatically make system-level dependencies identical. Record those prerequisites in the deployment configuration. Keep a previous complete release available so rollback restores the interpreter and dependencies together with application code.
Verification, release SLO and SOP
Start the packaged candidate with the exact production command and account. Exercise an endpoint that imports representative dependencies, then test restart and rollback. Confirm that no import comes from a developer directory or a package left globally on one machine. A successful dependency installation is not a successful application acceptance test.
An internal release-reliability SLO can track valid builds that start and pass acceptance in the supported runtime. Application availability and any customer SLA require their own definitions. The SOP should identify interpreter ownership, dependency-update policy, clean reconstruction, native-library prerequisites and rollback artifacts. Do not promise that a virtual environment alone provides container-like isolation or a security sandbox.
Explore software development and DevOps automation.
Technical reference
Python virtual environments, reviewed 19 October 2026. Follow documentation matching the installed product version.