Aufgrund der immer wieder auftauchenden Verständnis-Probleme bezüglich Pythons virtualenv's beschreibe ich hier eine komfortable Möglichkeit, mit externen Python Modulen umzugehen.
Seit einiger Zeit (auf Debian-Systemen: seit Bookworm) lassen sich externe Python Module ja nicht mehr systemweit mit pip install ... installieren und beim Versuch kommt die bekannte Meldung, die weitere Details enthält bzw. verlinkt:
error: externally-managed-environment × This environment is externally managed ╰─> To install Python packages system-wide, try apt install python3-xyz, where xyz is the package you are trying to install. If you wish to install a non-Debian-packaged Python package, create a virtual environment using python3 -m venv path/to/venv. Then use path/to/venv/bin/python and path/to/venv/bin/pip. Make sure you have python3-full installed. For more information visit http://rptl.io/venv note: If you believe this is a mistake, please contact your Python installation or OS distribution provider. You can override this, at the risk of breaking your Python installation or OS, by passing --break-system-packages. hint: See PEP 668 for the detailed specification.
Wie in der Meldung beschrieben soll also
- mit Hilfe des bei Python mitgelieferten Moduls venv eine virtuelle Umgebung (hier im Beispiel auch "venv" benannt) angelegt und
- diese dann aktiviert werden.
- In dieser aktivierten Umgebung werden dann mit pip die erforderlichen externen Module installiert
- und das Script - immer noch in der aktivierten Umgebung(!) - aufgerufen:
cd new_project
python3 -m venv venv
source venv/bin/activate
pip3 install some_external_module
./myscript.py
deactivate (Hinweis: Das frei wählbare Verzeichnis für die virtuelle Umgebung (bei python -m venv venv das zweite "venv") wird automatisch angelegt.)
Das ist natürlich problemlos so nutzbar, aber:
Zum installieren und nutzen von Python-Paketen gibt es durchaus einige weitere Alternativen.
Lange habe ich pipenv verwendet (https://pipenv.pypa.io/en/latest/).
Vor einiger Zeit habe ich aber uv kennen gelernt (https://github.com/astral-sh/uv).
Dies gefällt mir so gut, dass ich es inzwischen fast ausschließlich nutze, sobald Python-Module benötigt werden, die nicht (oder nicht in gewünschter Version) per apt installierbar sind.
Die einfach(st)e Installation erfolgt über den Auto-Installer (ohne sudo!):
curl -LsSf https://astral.sh/uv/install.sh | shBeispiel:
$ curl -LsSf https://astral.sh/uv/install.sh | sh
downloading uv 0.10.0 armv7-unknown-linux-gnueabihf
no checksums to verify
installing to /home/simonz/.local/bin
uv
uvx
everything's installed!
To add $HOME/.local/bin to your PATH, either restart your shell or run:
source $HOME/.local/bin/env (sh, bash, zsh)
source $HOME/.local/bin/env.fish (fish)
Die komplette Dokumentation zu uv ist erreichbar auf: https://docs.astral.sh/uv/
Nutzung:
cd new_project
uv init
uv add some_external_module
Beispiel:
$ cd new_project
$ uv init
Initialized project `new_project`
$ uv add icecream
Using CPython 3.13.5 interpreter at: /usr/bin/python3.13
Creating virtual environment at: .venv
Resolved 6 packages in 254ms
Prepared 5 packages in 849ms
Installed 5 packages in 105ms
+ asttokens==3.0.1
+ colorama==0.4.6
+ executing==2.2.1
+ icecream==2.1.10
+ pygments==2.19.2
Das virtualenv wird automatisch in ./.venv erzeugt und später genutzt.
Im Python-Script sind Shebang und die Importe wie üblich:
#!/usr/bin/env python3
import some_external_module Der Aufruf (mit Nutzung der .venv) lautet nun:
uv run myscript.py
Noch komfortabler geht es aber folgendermaßen, so dass ein Python-Script "self-contained" sein kann, also keine weiteren Dateien oder Spezial-Aufrufe benötigt:
Eine relativ neue Möglichkeit ist, eine bestimmte Syntax zu Beginn des Scripts zu nutzen (inline script metadata: https://packaging.python.org/en/latest/spec…script-metadata).
So können weitere Tools (hier uv) ermitteln, was benötigt wird und das Script auch gleich ausführen:
(siehe https://docs.astral.sh/uv/guides/scri…executable-file)
#!/usr/bin/env -S uv run --script
#
# /// script
# requires-python = ">=3.12"
# dependencies = ["icecream", "pysnooper"]
# ///
from icecream import ic
import pysnooper
Das Script muss noch ausführbar gemacht werden:
chmod a+x myscript.py
Nun ist das Script direkt(!) aufrufbar:
./myscript.py
Hier wird das venv on-the-fly erzeugt (in ~/.cache/uv/...) und genutzt, ohne dass der User das explizit angeben oder beachten muss.
Sehr bequem und sehr performant!
Da ist ein übergeordnetes Projektverzeichnis tatsächlich sinnvoll. Einfach nur venv würde ich das Verzeichnis darin aber trotzdem nicht nennen, aber vielleicht bin ich auch der einzige, der sich daran stört.
