Python venv, pipx of uv op Ubuntu server gebruiken
Krijgt u de foutmelding externally-managed-environment op Ubuntu? Ontdek wanneer u kiest voor venv, pipx of uv en hoe u deze correct koppelt aan systemd voor uw server.
Waarom pip install mislukt op een nieuwe Ubuntu-server
De keuze tussen een Python venv, pipx en uv op een server hangt af van één vraag: wat installeert u? Applicatie-dependencies horen thuis in een virtuele omgeving binnen de eigen map van de applicatie. Command-line tools die u op naam wilt kunnen aanroepen, horen thuis in pipx. uv voert beide taken uit en voegt een lockfile toe, wat relevant wordt zodra een tweede machine dezelfde omgeving moet bouwen. Geen van deze tools installeert echter in de systeem-Python, omdat een moderne Ubuntu-server dit ronduit weigert.
Voer sudo pip install requests uit op Ubuntu 24.04 en pip stopt voordat het ook maar één bestand downloadt.
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.
If you wish to install a non-Debian packaged Python application,
it may be easiest to use pipx install xyz, which will manage a
virtual environment for you.
note: If you believe this is a mistake, please contact your Python installation or OS distribution provider. You can override this behaviour by passing --break-system-packages.Dit is PEP 668 (Python enhancement proposal 668, "externally managed environments") dat zijn werk doet. Debian en Ubuntu plaatsen een markeringsbestand naast de interpreter op /usr/lib/python3.12/EXTERNALLY-MANAGED, en pip weigert te schrijven naar elke interpreter die zo'n bestand bevat.
Deze regel bestaat vanwege de sys.path-volgorde. apt installeert bibliotheken in /usr/lib/python3/dist-packages. pip, uitgevoerd als root tegen de systeem-interpreter, schrijft naar /usr/local/lib/python3.12/dist-packages, en de pakketbeheerder van Debian plaatst die map eerder in het zoekpad. Print dit zelf met python3 -c 'import sys; print(sys.path)' en lees de volgorde. De kopie die pip schreef, overschaduwt dus de kopie die apt installeerde voor elk programma op de machine dat onder /usr/bin/python3 draait, inclusief de eigen tools van de distributie. cloud-init importeert requests, jinja2 en PyYAML vanuit die interpreter. Upgrade een van deze met pip, kom terecht op een incompatibele release, en iets waar u nooit aan bent gekomen faalt bij de volgende boot met een traceback die een pakket noemt waarvan u niet wist dat het in de keten zat. apt registreert nog steeds zijn eigen versie als geïnstalleerd, dus niets waarschuwt u. De reparatie is het verwijderen van de kopie van pip met sudo pip uninstall --break-system-packages requests, omdat sudo apt reinstall python3-requests op zichzelf alleen de apt-kopie overschrijft die al werd overschaduwd.
De regel die volgt is kort. De systeem-Python is van de distributie. Installeer er niet in, upgrade de bibliotheken niet met pip en verwijder het bestand EXTERNALLY-MANAGED niet om de melding te laten verdwijnen. De enige taak voor /usr/bin/python3 is het bouwen van virtuele omgevingen.
venv versus pipx versus uv: de beslissingsregel
Kies op basis van wat u installeert, niet op basis van de tool waarover u onlangs het meest hebt gelezen.
- Een applicatie die u implementeert en uitvoert als een service, zoals een Django- of Flask-project: één virtual environment (venv) binnen de map van die applicatie.
- Een command-line tool die u op uw
PATHwilt hebben, zoalsansibleofhttpie: pipx, dat elke tool een eigen omgeving en één koppeling opPATHgeeft. - Een project dat een lockfile, snellere installaties of een Python-versie vereist die de distributie niet meelevert: uv, dat een standaard venv plus een
uv.lock-bestand produceert. - Een bibliotheek die een distributietool nodig heeft in plaats van uw code:
sudo apt install python3-<name>, de enige ondersteunde manier om iets toe te voegen aan de systeeminterpreter.
pipx en uv tool install doen hetzelfde werk, dus een machine die al over uv beschikt, heeft geen pipx nodig. Welk webframework u kiest, verandert hier niets aan: Django en Flask op een VPS verschillen in wat er in requirements.txt terechtkomt, niet in hoe de omgeving eromheen wordt gebouwd. Alles hieronder gebruikt Ubuntu 24.04 en de bijbehorende Python 3.12, dus pas de versie in de paden aan als de uwe afwijkt.
Bouw de per-applicatie venv
Ubuntu splitst de venv-module af van het basis Python-pakket. Op een minimale image mislukt de eerste poging daarom met een melding die precies aangeeft wat er ontbreekt.
The virtual environment was not created successfully because ensurepip is not
available. On Debian/Ubuntu systems, you need to install the python3-venv
package using the following command.
apt install python3.12-venvInstalleer deze module en maak vervolgens de omgeving aan als de gebruiker die eigenaar van de code zal zijn.
sudo apt update
sudo apt install -y python3-venv
sudo install -d -o deploy -g deploy -m 755 /srv/myapp
sudo -u deploy python3 -m venv /srv/myapp/.venv
sudo -u deploy /srv/myapp/.venv/bin/pip install -r /srv/myapp/requirements.txtLet op wat er niet aanwezig is: geen source, geen activate. /srv/myapp/.venv/bin/pip installeert in die omgeving vanwege de locatie van het binaire bestand, niet door iets dat u naar de shell heeft geëxporteerd. Controleer dit voordat u verdergaat.
/srv/myapp/.venv/bin/python -c 'import sys; print(sys.prefix)'Dit print /srv/myapp/.venv. Als het /usr print, voert u de systeem-interpreter uit en zijn uw pakketten op een locatie terechtgekomen die niet de bedoeling was.
Twee eigenschappen van een venv bepalen wat u er daarna mee kunt doen. Een venv is niet verplaatsbaar, omdat elk entry-point script in bin/ een absoluut shebang-pad bevat: head -1 /srv/myapp/.venv/bin/pip leest #!/srv/myapp/.venv/bin/python. Hernoem de bovenliggende map en deze scripts falen met bad interpreter: No such file or directory. Een venv koppelt ook de interpreter die deze heeft aangemaakt, vastgelegd als de home-regel in /srv/myapp/.venv/pyvenv.cfg, en bin/python3 is een symlink naar /usr/bin/python3. Upgrade de release zodat dat pad nu naar een nieuwere Python leidt, en de nieuwe interpreter zoekt naar pakketten in een lib/python3.13-map die de venv niet heeft, waardoor de service bij het opstarten stopt met ModuleNotFoundError. Voor beide gevallen geldt dezelfde oplossing: verwijder de venv en bouw een nieuwe vanuit requirements.txt. Het opnieuw opbouwen duurt enkele seconden. Kopieer nooit een venv tussen machines.
Waar de venv zich bevindt en wie de eigenaar is
Plaats deze naast de code op /srv/myapp/.venv en houd één venv per applicatie aan. De implementatie is dan één enkele map, de systemd-unit krijgt een pad dat nooit verandert en twee applicaties kunnen elkaar nooit verstoren door een gedeelde update van dependencies. Plaats een venv nooit op een locatie waar uw webserver direct bestanden publiceert, aangezien deze uw dependencies en vaak ook uw configuratie bevat.
Eigenaarschap verdient enige aandacht. Laat een deploy-gebruiker de eigenaar zijn van de code en de omgeving, en geef het service-account alleen lees- en uitvoerrechten.
sudo adduser --system --group --no-create-home myapp
sudo chown -R deploy:myapp /srv/myapp
sudo chmod -R o-rwx /srv/myappDe service kan nu zijn dependencies importeren, maar kan deze niet overschrijven. Dit betekent dat een bug voor code-executie in de webapplicatie niet stilletjes een bibliotheek op de schijf kan vervangen en een herstart kan overleven. Dezelfde redenering toegepast op de rest van de machine wordt behandeld in services draaien als gebruikers met minimale rechten.
pipx voor command-line tools
pipx installeert applicaties, geen libraries. Elke tool krijgt een eigen omgeving onder ~/.local/share/pipx/venvs/<name>, en de executables van die tool worden gelinkt naar ~/.local/bin, zodat twee tools die verschillende versies van dezelfde library nodig hebben nooit conflicteren.
sudo apt update
sudo apt install -y pipx
pipx ensurepath
pipx install httpiepipx ensurepath voegt ~/.local/bin toe aan PATH door uw shell-opstartbestand te bewerken. Het kan de shell waarin u zich al bevindt niet wijzigen, dus http: command not found direct na de installatie betekent meestal dat u nog niet opnieuw bent ingelogd. De standaard ~/.profile van Ubuntu voegt ~/.local/bin alleen toe wanneer die directory bij het inloggen al bestaat; daarom treedt dit probleem eenmalig op bij een nieuw account en daarna nooit meer.
Wijs pipx naar een library en het zal weigeren, met een melding die begint met:
No apps associated with package requests.Dat is de tool die u vertelt dat het het verkeerde instrument is. Libraries horen thuis in de venv van een applicatie.
Het detail dat op een server van belang is, is de locatie. Een standaard pipx install plaatst alles onder de home-directory van één gebruiker. Een systemd-unit die draait als myapp kan dit niet zien, een root-cronjob kan dit niet zien, en sudo zal het ook niet vinden, omdat secure_path in /etc/sudoers de PATH vervangt door een vaste lijst. Voor een tool die de gehele machine moet kunnen gebruiken, installeert u deze globaal.
sudo pipx install --global ansible
sudo pipx ensurepath --globalDe --global-vlag plaatst omgevingen in /opt/pipx en linkt executables naar /usr/local/bin, wat in de standaard PATH staat en binnen secure_path valt. Controleer eerst uw versie met pipx --version, aangezien Ubuntu 24.04 pipx 1.4.3 verpakt, wat ouder is dan --global, en een oudere pipx antwoordt met unrecognized arguments: --global. Stel bij die versie de twee gedocumenteerde directories zelf in:
sudo env PIPX_HOME=/opt/pipx PIPX_BIN_DIR=/usr/local/bin pipx install ansible
command -v ansiblecommand -v ansible hoort /usr/local/bin/ansible te printen. Als het een pad onder /home print, is de tool in het account van een enkele gebruiker terechtgekomen en zal geen enkele service deze vinden.
uv wanneer u een lockfile wilt
uv is een enkel binair bestand van Astral dat de functionaliteit van pip, venv en pip-tools combineert, en daarnaast ook interpreters kan downloaden. Het is snel genoeg om het verschil te merken op een kleine VPS, en het schrijft een echte lockfile.
Het officiële installatieprogramma plaatst uv en uvx in ~/.local/bin:
curl -LsSf https://astral.sh/uv/install.sh | sh
uv --versionHet direct naar een shell op een server pipen van een script vereist enige voorzichtigheid. Pin de versie in de URL en lees het bestand voordat u het uitvoert:
curl -LsSf https://astral.sh/uv/0.12.3/install.sh -o uv-install.sh
less uv-install.sh
sh uv-install.shpipx install uv werkt ook, wanneer pipx al aanwezig is. uv is één op zichzelf staand binair bestand zonder eigen Python-afhankelijkheid, dus het kopiëren naar /usr/local/bin is een geldige manier om het beschikbaar te maken voor elke gebruiker op de server.
Voor een project met een pyproject.toml bestaat de workflow uit vier commando's, waarvan alleen de laatste op de server wordt uitgevoerd.
uv init myapp
uv add flask gunicorn
uv lock
uv sync --frozen --no-devuv lock schrijft uv.lock, een platformonafhankelijke lockfile met exact opgeloste versies, die u samen met uw code commit. uv sync bouwt .venv in de projectmap om hiermee overeen te stemmen. Op de server is --frozen de relevante vlag: de documentatie definieert dit als het gebruik van de versies in de lockfile als de bron van waarheid, in plaats van te controleren of de lockfile up-to-date is; dit is het gewenste gedrag voor een deployment. --no-dev laat de groep met ontwikkelafhankelijkheden weg.
Een bestaand requirements.txt-project heeft geen conversie nodig, omdat uv de taal van pip spreekt:
uv venv /srv/myapp/.venv
uv pip install --python /srv/myapp/.venv/bin/python -r /srv/myapp/requirements.txtHet resultaat is een gewone virtuele omgeving met één verschil: uv installeert pip er niet in, dus .venv/bin/pip en .venv/bin/python -m pip werken niet tenzij u de omgeving aanmaakt met uv venv --seed. Installeer in plaats daarvan met uv pip. Niets verderop in deze handleiding voert pip uit binnen de omgeving, dus er verandert niets.
Eén standaardinstelling van uv is het waard om te kennen voordat u het op een server gebruikt. De instelling python-preference staat standaard op managed, wat gedocumenteerd is als het verkiezen van "degenen die door uv worden gedownload en geïnstalleerd" boven interpreters die al op het systeem aanwezig zijn. Dus uv venv --python 3.13 op een server die alleen 3.12 bevat, haalt stilletjes 3.13 op naar ~/.local/share/uv/python in plaats van te falen. Dat is handig op een laptop en verrassend op een server, omdat uw service nu afhankelijk is van een interpreter die in een thuismap leeft en die apt upgrade nooit zal patchen. Stel python-preference in op only-system in uv.toml als u de interpreter van de distributie wilt gebruiken. Als u de omgeving ergens anders wilt dan in de projectmap, specificeert UV_PROJECT_ENVIRONMENT de map die gebruikt moet worden voor een virtuele projectomgeving.
Verwijs systemd naar de venv-interpreter, niet naar activate
Dit is het punt waar de meeste Python-implementaties falen. De oorzaak is een misverstand over wat activate doet.
bin/activate is een shell-script. Het voegt de bin-directory van de venv toe aan PATH, stelt VIRTUAL_ENV in, slaat de oude waarden op zodat deactivate deze kan herstellen, en wijzigt uw prompt. Het bevat niets dat de interpreter zelf leest. Activering is enkel een gemak voor een gebruiker die python typt in een terminal.
Wat de omgeving daadwerkelijk selecteert, is welk interpreter-bestand u uitvoert. Wanneer /srv/myapp/.venv/bin/python start, zoekt de site-module van Python naar een pyvenv.cfg-bestand in de directory van het uitvoerbare bestand en één niveau daarboven. Het vinden van /srv/myapp/.venv/pyvenv.cfg stelt sys.prefix in op de venv, waardoor de site-packages van die venv in sys.path terechtkomt. Dat is het volledige mechanisme. Het vereist geen omgevingsvariabele en geen shell.
Deze unit start daarom nooit:
[Service]
ExecStart=source /srv/myapp/.venv/bin/activate && gunicorn app:appmyapp.service: Failed to locate executable source: No such file or directory
myapp.service: Failed at step EXEC spawning source: No such file or directory
myapp.service: Main process exited, code=exited, status=203/EXECExecStart is geen shell-opdrachtregel. systemd voert een programma direct uit, dus er is geen source-builtin, && wordt doorgegeven als een letterlijk argument en er vinden geen shell-expansies plaats, behalve de weinige die systemd zelf documenteert.
Deze unit start wel, maar stopt direct daarna:
[Service]
ExecStart=/usr/bin/python3 /srv/myapp/app.pyModuleNotFoundError: No module named 'flask'/usr/bin/python3 is de systeem-interpreter en de sys.path daarvan heeft uw venv nooit bevat. Dezelfde opdracht werkt in uw SSH-sessie alleen omdat u daar de venv had geactiveerd, waardoor de shell python3 via PATH oploste naar .venv/bin/python3.
Het verpakken van de opdracht in /bin/bash -c 'source ... && gunicorn ...' werkt wel. Het plaatst echter onnodig een shell tussen systemd en uw proces, terwijl één absoluut pad het probleem oplost:
[Unit]
Description=myapp web service
After=network-online.target
Wants=network-online.target
[Service]
Type=simple
User=myapp
Group=myapp
WorkingDirectory=/srv/myapp
Environment=PYTHONUNBUFFERED=1
Environment=PATH=/srv/myapp/.venv/bin:/usr/local/bin:/usr/bin:/bin
ExecStart=/srv/myapp/.venv/bin/gunicorn --workers 3 --bind 127.0.0.1:8000 app:app
Restart=on-failure
RestartSec=5
NoNewPrivileges=yes
PrivateTmp=yes
ProtectSystem=full
[Install]
WantedBy=multi-user.targetsudo systemctl daemon-reload
sudo systemctl enable --now myapp
systemctl status myapp
journalctl -u myapp -n 50 --no-pagersystemctl status myapp hoort active (running) te rapporteren met een Main PID die uw gunicorn-proces is. Als dit anders is, lees dan het logboek.
De regel Environment=PATH= is er niet voor ExecStart, die al een volledig pad bevat. Deze is bedoeld voor de processen die uw applicatie start. Een service erft een korte standaard PATH van systemd. Python-code die subprocess.run(["ffmpeg", ...]) aanroept, of een beheeropdracht die een console-script uit de venv aanroept, zal daarom niet vinden wat nodig is. Het vooraan plaatsen van de bin-directory van de venv is het enige onderdeel van activate dat een service daadwerkelijk gebruikt. Controleer wat de unit daadwerkelijk heeft ontvangen met systemctl show -p Environment myapp.
Dezelfde regel geldt voor geplande taken. Op Ubuntu geeft cron een taak niet de PATH van uw shell of van de daemon door: tenzij de crontab zelf PATH instelt, krijgt elke taak de gecompileerde standaard /usr/bin:/bin, en /etc/environment overschrijft dit niet. Dat bevat nooit uw venv, dus een crontab-regel die python3 /srv/myapp/cleanup.py leest, voert de systeem-interpreter uit en faalt om drie uur 's nachts met ModuleNotFoundError. cron mailt de fout naar de eigenaar van de crontab, of naar het MAILTO-adres als u dat heeft ingesteld, wat op de meeste servers betekent dat het in een lokale mailbox belandt die niemand leest. Zonder geïnstalleerd mailprogramma gooit cron de uitvoer weg en schrijft alleen No MTA installed, discarding output naar het systeemlogboek. Schrijf ook daar het absolute venv-pad. Om die uitvoer in het logboek te krijgen en een overzicht van de laatste uitvoering te bewaren, gebruikt u een systemd service en timer paar met dezelfde ExecStart-regel.
Vervangt Docker deze beslissing?
Een container heeft een eigen bestandssysteem, waardoor de vraag van vorm verandert in plaats van verdwijnt. In een officiële image zoals python:3.12-slim is Python ingebouwd in /usr/local en bevat deze geen EXTERNALLY-MANAGED-markering. Daarom is pip install als root de beoogde manier om pakketten toe te voegen en voegt een venv weinig toe. Bouw in plaats daarvan FROM ubuntu:24.04 en u komt externally-managed-environment opnieuw tegen in de image, om dezelfde reden als op de host: het is de interpreter van de distributie die het markeringsbestand van de distributie bevat.
Veel images gebruiken nog steeds een venv, omdat dit een multi-stage build eenvoudig maakt. De builder-fase installeert in /opt/venv, en de runtime-fase kopieert die ene map en laat de compilers achter. Het activate-probleem reist mee. Een RUN source /opt/venv/bin/activate-regel heeft alleen invloed op de shell van die build-laag, dus bij runtime start de container op de systeem-interpreter en genereert ModuleNotFoundError. Stel ENV PATH="/opt/venv/bin:$PATH" in, of geef CMD het absolute pad /opt/venv/bin/gunicorn. Het is dezelfde bug als die in systemd, maar dan in een ander bestand.
Een container vervangt dus de vraag over de interpreter, omdat de image de interpreter en alles daaronder vastzet. Het vervangt niet de vraag over het vastzetten van versies. Een image die is gebouwd op basis van een niet-vastgezet requirements.txt zal volgende maand andere versies resolven. Dit betekent dat de image-tag reproduceerbaar is, terwijl de build die deze heeft geproduceerd dat niet is. Een lockfile zoals uv.lock, of een volledig vastgezet requirements-bestand, dicht dat gat, ongeacht of u containers gebruikt of niet. En wanneer één applicatie op één VPS onder systemd draait, verplaatst een container deze beslissing grotendeels naar een Dockerfile, aangezien systemd een gefaald proces al opnieuw opstart en de uitvoer ervan vastlegt in de journal. Docker draaien op een VPS is zinvol wanneer u wilt dat de gebouwde image zelf het object is dat u uitrolt.
FAQ
Kan ik gewoon pip install gebruiken met --break-system-packages?
Niet op een server die u draaiende moet houden. De flag doet precies wat de naam zegt: het verwijdert de beveiliging en pip schrijft naar /usr/local/lib/python3.12/dist-packages, dat in de zoekvolgorde vóór de apt-directory op sys.path komt. Uw versie overschrijft vervolgens de versie van de distributie voor elk systeemscript dat onder /usr/bin/python3 draait. Omdat apt nog steeds denkt dat de eigen versie is geïnstalleerd, wordt het conflict niet gedetecteerd totdat er iets defect raakt. Binnen een container-image die u telkens vanaf nul opbouwt, blijft de schade beperkt tot die image; daar is het verdedigbaar. Op een machine die u onderhoudt, maakt u een venv aan. Dat is slechts één commando.
Waar moet de virtual environment op een server staan?
Binnen de eigen directory van de applicatie, als /srv/myapp/.venv, in eigendom van een deploy-gebruiker, waarbij het service-account alleen lees- en uitvoerrechten heeft. Gebruik één venv per applicatie, omdat een gedeelde venv betekent dat een upgrade voor de eerste applicatie de tweede kan breken. Verplaats of kopieer een venv niet nadat deze is aangemaakt: elk entry-point-script in de bin/-directory bevat dat absolute pad in de shebang-regel, waardoor een verplaatste venv faalt met bad interpreter: No such file or directory. Verwijder deze in plaats daarvan en bouw hem opnieuw op vanuit requirements.txt.
Waarom faalt mijn systemd-service met ModuleNotFoundError?
Omdat de unit een interpreter uitvoert die niet die van de venv is. Voer systemctl cat myapp uit en lees ExecStart. Het moet verwijzen naar /srv/myapp/.venv/bin/python, of een console-script uit diezelfde bin/-directory, via een absoluut pad. Het direct sourcen van activate in ExecStart werkt niet, omdat ExecStart geen shell is en systemd rapporteert Failed to locate executable source met status=203/EXEC. Voeg Environment=PATH=/srv/myapp/.venv/bin:/usr/local/bin:/usr/bin:/bin toe zodat elk subproces dat uw code start ook de tools van de venv vindt.
Moet ik uv gebruiken in plaats van venv en pip?
Gebruik uv wanneer u een lockfile wilt, wanneer de installatietijd traag genoeg is om hinderlijk te zijn, of wanneer u een Python-versie nodig heeft die uw distributie niet levert. Het creëert een standaard venv, dus de systemd-unit en de bestandsindeling veranderen niet, en uv sync --frozen installeert precies wat in het lockfile is vastgelegd. Als een enkele applicatie vanuit git wordt uitgerold met een vastgezet requirements.txt en de installatie in seconden is voltooid, dan is python3 -m venv al voldoende en heeft u één binary minder om bij te houden op de server.