Background: There are a couple of excellent posts on Stack Overflow that explain why “error: externally-managed-environment” is thrown when trying to execute pip install -r requirements.txt – in modern Python one must always create a virtual environment for each project so as to install it’s dependencies locally and avoid clashing with Linux’ own package manager. In my case however I still kept getting the same error even after having created and activated my project’s own virtual environment. This post then is an aide memoire to myself and to help anyone else that end up in the same situation.

Steps to set up a basic Python environment from scratch on a fresh Ubuntu install

The Ubuntu guidance page tells you to run sudo apt install -y python3-full, which might be simple but also brings with it all the class libraries plus the graphical IDE. If you don’t want all that, the following will provide you a minimal environment and use several hundred MB less disk space :

  1. Update the package lists: sudo apt-get update
  2. Upgrade what’s installed: sudo apt-get upgrade
  3. Install the Python package manager: sudo apt install -y python3-pip
  4. If any packages failed to install, fix missing: sudo apt-get install -y --fix-missing python3-pip
  5. Install virtual environment (venv) support: sudo apt install python3.12-venv

Steps to set up a virtual environment for a given existing Python project

As mentioned in the preamble, the modern way is to create separate virtual environments (venvs) for each project you’re working on, so as to install that project’s dependencies separately from the system Python (and from other projects). To do so for an existing project:

  1. Change to the project’s working directory: cd <path to project>
  2. Create a virtual environment there: python3 -m venv <venv name>. This will be created as a subfolder within the project directory, so keep it short.
  3. Activate the venv: source <venv name>/bin/activate. You’ll notice the command prompt will now be prefixed with (<venv name>)
  4. Install pip in the venv: python -m pip install --upgrade pip. This is the step that was missing in other guides I found.
  5. Confirm that the venv has it’s own Python: which python. It should list the Python interpreter installed within <venv name>/bin and not /usr/bin.
  6. Confirm that the venv has it’s own pip: which pip. It should list the pip executable installed within <venv name>/bin and not /usr/bin.

Note that once working within the venv, sudo is no longer required (perhaps explicitly should not be used)

Finally…

With all the above in place, I could finally run pip install -r requirements.txt and not get the dreaded “externally-managed-environment” message.