Python on Debian

Python is already on devserver, because Debian's own tools depend on it. That is exactly what makes it easy to get wrong. If you install packages into the Python that the operating system uses, you can break the operating system. Debian 12 and 13 refuse to let you do it by accident, and this chapter explains why, and gives you three clean ways of working: virtual environments for projects, pipx for command-line tools, and pyenv for when you need a different Python version. It builds directly on the “which copy runs?” habit from Chapter 3.

The Python You Already Have

Debian 13 ships Python 3.13 (the current package is 3.13.5). Check it with the tools from Chapter 3:

You should see one copy, /usr/bin/python3, owned by a Debian package. That is the system Python. Note there is no plain python command, only python3. (An optional package, python-is-python3, adds one, but you do not need it.)

A fresh desktop install often has the interpreter but not everything you need to develop. Install the extras now:

Why pip install Refuses

Now try the thing every tutorial tells you to do:

On Debian 12 and 13 this stops with an error that begins error: externally-managed-environment, and explains that the environment is managed by the operating system. This is not a fault. Debian is following PEP 668, a Python standard that lets a distribution mark its Python as “externally managed”, so pip will not modify it. Debian marks the interpreter with a file named EXTERNALLY-MANAGED in the standard-library directory, and pip checks for it.

Which Tool for Which Job

Instead of overriding the rule, choose the right tool. The question to ask is: what am I installing?

Virtual Environments

A virtual environment (venv) is a folder containing its own copy of the Python interpreter link and its own place for packages. Create one inside each project, and activate it when you work there:

After source .venv/bin/activate, type -a python3 lists the venv's copy first. That is the whole trick: activation puts the environment's bin directory at the front of your PATH, so python3 and pip now mean the ones inside the venv. pip install requests works, and the package lands inside .venv, not in the system. deactivate puts the PATH back.

Recording and recreating an environment

Because a venv is disposable, you can delete .venv and rebuild it from requirements.txt in seconds. That is what makes it safe to experiment.

pipx: Tools, Not Libraries

Some Python software is not a library for your project but a program you want to run: a code formatter, an HTTP client, a linter. pipx installs each one into its own private virtual environment and puts its command where you can run it. The Debian wiki recommends pipx as the easiest way to work with the externally-managed rule.

The http command works from anywhere, yet its libraries are isolated and cannot clash with anything else. The command itself sits in ~/.local/bin, which Chapter 3 listed as a place where software installed for one user lives outside apt.

pyenv: Other Python Versions

Debian 13 gives you one Python, 3.13. That is fine most of the time. But a project may need an older version to match a server, or you may want to test on a newer one. pyenv builds extra Python versions from source into your home directory, and lets you choose per project.

Because it compiles Python, pyenv needs a set of build libraries first. The pyenv project's own suggested list for Debian is:

pyenv's documentation offers a one-line installer that pipes a downloaded script into bash. It is worth knowing that running a downloaded script blindly is exactly what the verify-before-you-trust habit from Chapter 1 warns against, so this course uses the other documented method: clone the project and read what you are running.

Then add these lines to ~/.bashrc (and the same lines to ~/.profile, as the pyenv documentation advises):

Open a new terminal, then use it:

pyenv local writes a .python-version file, so a project always uses the version you chose for it, and the file can be committed to Git. Building takes a few minutes; that is normal.

When apt Is the Right Answer

Debian packages many Python libraries as python3-NAME (for example python3-requests). Use apt when a library is needed by a program you installed with apt, or when you want a tool that is part of the operating system's own ecosystem. The catch is that the version is whatever Debian froze at release, often older than PyPI's latest, which is why projects use venvs. Check with the Chapter 3 tools before you choose:

For deeper Python work, see the Python Fundamentals course. Here we only need the machine to be set up so that course, and every project after it, starts cleanly.

Hands-On Exercises