VPS Tutorials
Fix pip's externally-managed-environment error with venv or pipx
When system Python blocks dependency installation, distinguish project libraries, CLI tools and system packages. Choose venv or pipx and diagnose missing ensurepip or service import failures.

Running pip install -r requirements.txt on a VPS returns error: externally-managed-environment. This usually means the Python installation is maintained by the operating system's package manager and pip has been instructed not to modify it directly. It is not normally a network, package-mirror or file-permission problem.
Use a dedicated venv for a Python project, consider pipx for a standalone command-line application, and prefer apt for distribution-managed system components. Choosing the right environment avoids a forced installation that later breaks system utilities or another project.
From the project directory, run:
command -v python3
python3 --version
python3 -m pip --version
python3 -c "import sys; print(sys.executable); print(sys.prefix); print(sys.base_prefix)"
python3 -m pip ties pip to the chosen interpreter, reducing ambiguity when pip and pip3 refer to another installation. Equal paths on the final two lines normally mean you are outside a venv; different paths indicate a virtual environment. A missing pip instead produces No module named pip, a separate problem.
The Python packaging specification uses the EXTERNALLY-MANAGED marker to identify an externally managed interpreter. Python is not broken, and deleting the marker is not the intended solution. Neither sudo pip nor pip install --user should be a general fix for this error.
| What you need | Installation environment | How to use it |
|---|---|---|
| Dependencies for a website, API or script project | That project's venv | Run the project with .venv/bin/python |
| A standalone Python CLI application | pipx | Use the executable exposed by pipx |
| A system component packaged by the distribution | apt or its equivalent | Follow the distribution's documentation |
pipx maintains an isolated environment for a CLI and exposes its commands; see the PyPA command-line application guide. It is not a substitute for installing a project's arbitrary requirements.txt.
For an existing Linux project, enter the directory containing its trusted requirements.txt, then run:
python3 -m venv .venv
.venv/bin/python -m pip --version
.venv/bin/python -m pip install -r requirements.txt
.venv/bin/python -m pip check
If .venv already exists, inspect its interpreter, dependency specification and running services before replacing it. Create new environments with a Python version the project supports, rather than changing major versions merely to make installation succeed.
Use the project's lockfile or deployment instructions for dependency versions. Restoring a deployment is not a reason to upgrade every package; successful installation can still introduce application incompatibilities.
An explicit interpreter path works without activating the environment. The venv documentation explains that activation primarily changes the current shell's PATH; directly calling the venv interpreter also works.
For convenient interactive use in Bash or Zsh:
source .venv/bin/activate
python -m pip --version
python -c "import sys; print(sys.executable)"
deactivate
Python and pip should now resolve inside the project's .venv. deactivate restores the shell settings; it neither uninstalls packages nor removes the environment. Run the project's import, startup or health checks after installation. A passing pip check only checks declared dependency compatibility, not application behavior.
Minimal Ubuntu or Debian installations may report ensurepip is not available. When using the distribution's default python3, install venv support from its repository:
sudo apt update
sudo apt install python3-venv
Then create the project environment. The Ubuntu Python environment guide also describes python3-full, which includes venv support. Choose according to the missing components; do not remove system Python to install project dependencies.
An interpreter from another repository, source build, pyenv or control panel may not match the default python3-venv. Confirm which interpreter creates the environment and obtain support from the same source. Do not alter the /usr/bin/python3 symlink to accommodate one project.
Certificate failures, connection timeouts, unavailable compatible versions and extension-build errors are different issues. Investigate the package index, network, Python version, platform and build dependencies. Adding privileges or deleting the environment marker does not address them.
On Ubuntu or Debian with pipx available in the repository, install it first:
sudo apt install pipx
pipx ensurepath
pipx list
Follow the application's official instructions for pipx install 应用的发行包名. Replace the example package name with a distribution that actually provides a CLI, not an arbitrary library. After ensurepath, reconnect over SSH or open a new shell if needed for the updated PATH to locate the command.
A successful pipx installation does not make that package importable by a website's interpreter; those environments are intentionally separate. Code that needs to import a library requires installation in its own venv. Distribution package names, PyPI names and import names can also differ, so do not guess an installation command from the missing module's name alone.
Activation affects only the current shell. Another user, a new SSH session or a background service does not automatically inherit it.
For a project located at /srv/myapp, configure the service to call /srv/myapp/.venv/bin/python with the correct working directory, user and environment. A web service can use its real entry point such as /srv/myapp/.venv/bin/gunicorn, rather than assuming a bare python resolves to the project environment.
Do not treat source .venv/bin/activate as a normal executable in systemd's ExecStart. See the Python deployment guide for the full setup, and systemd troubleshooting for startup failures.
When moving to another VPS, avoid simply copying .venv. Virtual environments may contain absolute paths and platform-specific files. Preserve the project, locked dependencies and required configuration, recreate its environment on the destination and verify the service.
The pip installation options define this switch as permission to modify an externally managed Python installation. It bypasses the restriction but provides neither project isolation nor compatibility guarantees with apt-managed packages.
Use venv for a project, pipx for a CLI and distribution packages for system components. If packages were already forced into system Python, preserve installation records, identify affected utilities and plan a repair. Do not broadly uninstall unfamiliar system dependencies.
The original article records eight checks with macOS Python 3.14.0 and pip 25.2. A temporary venv installed and imported a locally built offline demonstration package; the base interpreter and another project's environment could not import it. Activation and direct interpreter paths behaved as expected, and pip check passed. These checks did not reproduce Ubuntu's externally managed error and did not test apt, pipx, network downloads, real project compilation or a systemd service.