DEV Community

Big Mazzy
Big Mazzy

Posted on

Fix externally-managed-environment on Ubuntu 24.04 with venv

#linux #ubuntu #tutorial #devops

TL;DR: Install python3-venv, create a virtual environment for your app, and use that environment’s pip to install FastAPI.

The problem

On Ubuntu 24.04, a pip install into the system Python can fail with this message:

error: externally-managed-environment
Enter fullscreen mode Exit fullscreen mode

For example, the command below tries to install FastAPI into the Python environment managed by Ubuntu:

python3 -m pip install fastapi
Enter fullscreen mode Exit fullscreen mode

That error can be confusing if you are used to running pip directly on other systems. It does not mean Python is broken, and it does not mean FastAPI is unavailable. Ubuntu is stopping pip from changing packages in its system-managed Python environment.

The practical fix is to create a separate virtual environment for your application. Install the application dependency there, keeping it apart from packages installed and maintained by Ubuntu.

Why it happens

Ubuntu uses apt to manage its system Python packages. That Python installation is part of the operating system, and other system tools may rely on its packages and versions. If pip changes those packages independently, it can create conflicts or leave system software in an unexpected state.

The externally managed environment error is a guardrail: it prevents pip from writing into that protected system environment. For an application, use a virtual environment instead. A venv gives the app its own place for Python dependencies, separate from system packages.

On a clean Ubuntu image, you may need to install the venv support package first. Without it, creating the environment can fail with an ensurepip error. Installing python3-venv with apt provides the support needed for the next step.

Step-by-step fix

  1. First, reproduce the issue by attempting the system-level install. This command is included to show what triggers the error; it is not the command to use for installing the app dependency. 
   python3 -m pip install fastapi
Enter fullscreen mode Exit fullscreen mode

Ubuntu may respond with error: externally-managed-environment. That is the expected protection for the managed Python environment.

  1. Install the venv support package and create a virtual environment for the app. The command uses apt for Ubuntu’s system package and then creates the environment at ~/app/.venv. 
   sudo apt install -y python3-venv && python3 -m venv ~/app/.venv
Enter fullscreen mode Exit fullscreen mode

If the app directory does not exist, venv creation may report an error. In this example, ~/app/.venv is the target path; keep the same path in the install and verification steps so they use the environment you created.

  1. Install FastAPI using the pip executable inside the virtual environment. 
   ~/app/.venv/bin/pip install fastapi
Enter fullscreen mode Exit fullscreen mode

This uses the environment’s pip directly. Activation is optional: a full executable path makes clear which pip is being run and avoids relying on shell activation.

How to verify

Ask the virtual environment’s pip to show FastAPI’s package information:

~/app/.venv/bin/pip show fastapi
Enter fullscreen mode Exit fullscreen mode

The output includes the package name:

Name: fastapi
Enter fullscreen mode Exit fullscreen mode

That name confirms FastAPI is installed in the environment queried by this command. The important detail is the executable path: ~/app/.venv/bin/pip points to the app’s virtual environment, rather than Ubuntu’s system pip. If you use this approach for another application dependency, use the same environment’s pip path for both installation and inspection.

Common mistakes

  • Installing into system Python again: Running python3 -m pip install fastapi repeats the operation that Ubuntu blocks. Use the venv’s pip path for the application package.
  • Skipping python3-venv: On a clean image, venv support may be missing, and environment creation can stop with an ensurepip error. Install the Ubuntu package before creating the venv.
  • Using a different pip by accident: A bare pip command may refer to a different Python environment. The full path in these steps makes the target explicit.
  • Checking the wrong environment: Run pip show through the same ~/app/.venv/bin/pip path used for installation. Otherwise, the result may describe a different Python environment.
  • Assuming activation is required: You can use the virtual environment’s executable paths directly, so these steps do not depend on activation.
  • Treating sample details as literal server values: Any IP addresses, process IDs (PIDs), or session numbers in examples are placeholders where relevant; they are not values to copy as part of this Python fix.

If you want a clean Ubuntu box to practice on, PowerVPS is a reasonable choice: https://powervps.net/?from=32

Watch more fixes on Server Lab: https://www.youtube.com/channel/UCov7rfWAnS4c2wF5E9V1Yag

Top comments (0)