Hoe Python venv te gebruiken: van creatie en activering tot requirements.txt en beheer

AI_Manager

De essentie van het gebruik van Python venv is het scheiden van de installatieruimte voor Python-pakketten per project. venv is een standaard Python-bibliotheekfunctie. Als u pakketten rechtstreeks in de systeem-Python installeert, kunnen versies conflicteren met tools van het besturingssysteem of andere applicaties. Door virtuele omgevingen te gebruiken, kan elk project de benodigde versies onafhankelijk beheren.

Dit artikel legt vanuit een praktisch perspectief uit hoe u virtuele omgevingen aanmaakt en controleert op Linux, macOS en Windows, inclusief requirements.txt, offline wheelhouses, systemd-services, veilig verwijderen en probleemoplossing. Vervang de Python-versie en projectpaden in de opdrachten door de waarden die in uw eigen omgeving van toepassing zijn voordat u ze kopieert.

Snel aan de slag met Python venv

Het eenvoudigste patroon is om een .venv aan te maken in de projectmap en pip uit te voeren met de Python van die omgeving. In plaats van alleen pip aan te roepen, is het gebruik van python -m pip duidelijker om te garanderen dat de gekozen interpreter en pip overeenkomen.

mkdir -p ~/projects/sample-app
cd ~/projects/sample-app

python3 --version
python3 -m venv .venv
source .venv/bin/activate

python -m pip --version
python -m pip install --upgrade pip
python -m pip install requests
python -c "import requests; print(requests.__version__)"

deactivate

De map van de virtuele omgeving is geen broncode. Het is cruciaal om .venv/ niet naar Git te pushen, maar deze zo te beheren dat de omgeving op elk moment opnieuw kan worden aangemaakt met behulp van afhankelijkheidsbestanden.

Wat is Python venv en hoe zorgt het voor isolatie?

Geen volledige kopie van Python, maar een afzonderlijke uitvoeringscontext

Wanneer u een virtuele omgeving aanmaakt, worden pyvenv.cfg, een map met uitvoerbare bestanden en een onafhankelijke site-packages in de doelmap geplaatst. Afhankelijk van het platform en de aanmaakopties kunnen de Python-uitvoerbare bestanden kopieën of symbolische koppelingen zijn. Daarom is venv geen technologie die het besturingssysteem isoleert zoals een container; het is afhankelijk van de basis-Python en de bibliotheken van het besturingssysteem die zijn gebruikt voor de creatie.

python3 -m venv .venv

find .venv -maxdepth 2 -type f -o -type l | sort | head -30
cat .venv/pyvenv.cfg

Hoe u nauwkeurig controleert of een virtuele omgeving actief is

Het activeringsscript voegt de map met uitvoerbare bestanden van de omgeving toe aan het begin van de PATH. Omdat activering echter niet verplicht is, kan het beoordelen op basis van alleen de VIRTUAL_ENV-variabele leiden tot fouten. Binnen Python is het vergelijken van sys.prefix en sys.base_prefix een nauwkeurigere methode.

python - <<'PY'
import sys

print("executable   :", sys.executable)
print("prefix       :", sys.prefix)
print("base_prefix  :", sys.base_prefix)
print("inside venv  :", sys.prefix != sys.base_prefix)
PY

Controlepunten vóór het aanmaken van een Python venv

Controleer eerst de werkelijke locatie en versie van de te gebruiken Python, en of de venv-module en pip-bootstrap beschikbaar zijn. Als er meerdere Python-versies op dezelfde server staan, specificeer dan de gewenste interpreter zoals in python3.11.

command -v python3
python3 --version
python3 -m venv --help >/dev/null
python3 -m ensurepip --version

Sommige Linux-distributies bieden venv of pip aan als afzonderlijke pakketten. De pakketnaam verschilt per distributie en Python-versie, dus controleer de repository voordat u deze installeert. Het is veiliger om sudo pip install niet te gebruiken voor de systeem-Python.

# Algemeen voorbeeld voor Debian/Ubuntu-systemen
sudo apt update
sudo apt install python3-venv python3-pip

# Controleer voor RHEL/Rocky-systemen eerst de geleverde pakketten
sudo dnf list --available 'python3*' | grep -E 'pip|virtualenv'

Opdrachten voor aanmaken en activeren per besturingssysteem en shell

Controleer na activering het pad en de versie. De (.venv)-aanduiding in de prompt is slechts een gemak, dus controleer altijd het werkelijke pad van de interpreter om te voorkomen dat u per ongeluk in de verkeerde omgeving installeert.

command -v python
python --version
python -m pip --version
python -c "import sys; print(sys.executable)"

Hoe u Python venv uitvoert zonder activering

U hoeft niet per se source uit te voeren om Python venv te gebruiken. Voor cron, systemd en CI-taken is het voorspelbaarder en eenvoudiger voor loganalyse om het absolute pad van de Python binnen de omgeving direct aan te roepen in plaats van te vertrouwen op activeringsscripts.

# Linux/macOS
/opt/sample-app/.venv/bin/python /opt/sample-app/app.py
/opt/sample-app/.venv/bin/python -m pip list

# Windows PowerShell
.\.venv\Scripts\python.exe .\app.py

Python venv pakketinstallatie en beheer van requirements.txt

Roep pip altijd aan op basis van de huidige Python

python -m pip install --upgrade pip
python -m pip install 'requests>=2.32,<3'
python -m pip list
python -m pip check

pip check controleert of de gedeclareerde afhankelijkheden van de geïnstalleerde pakketten compatibel zijn. Door dit uit te voeren in combinatie met applicatietests na het installeren van pakketten, kunt u ontbrekende of conflicterende afhankelijkheden snel opsporen.

Het maken en reproduceren van omgevingssnapshots

pip freeze voert de versies van de huidige directe en indirecte afhankelijkheden uit, wat nuttig is voor het vastleggen van snapshots van de productieomgeving. Houd er echter rekening mee dat hetzelfde bestand mogelijk niet identiek kan worden geïnstalleerd als het besturingssysteem, de CPU of de Python-versie wijzigt, dus leg ook de uitvoeringscondities vast.

python -m pip freeze > requirements.txt
python -m pip check

# Reproduceren in nieuwe omgeving
python3 -m venv .venv-new
.venv-new/bin/python -m pip install --upgrade pip
.venv-new/bin/python -m pip install -r requirements.txt
.venv-new/bin/python -m pip check

Bestanden die in het project moeten worden opgenomen

# .gitignore
.venv/
__pycache__/
*.py[cod]
.env

# Versie en installatiestatus vastleggen
python --version
python -m pip --version
python -m pip freeze

Python venv beheren in afgesloten netwerken of offline omgevingen

In een afgesloten netwerk is het cruciaal dat de server met internetverbinding hetzelfde besturingssysteem, dezelfde CPU-architectuur en dezelfde Python major- en minor-versie gebruikt als de doelserver. Omdat wheels afhankelijk kunnen zijn van het platform en de Python ABI, kan het kopiëren van bestanden die op een andere pc zijn gedownload, leiden tot installatiefouten.

Een wheelhouse voorbereiden op een online server

python3 -m venv bundle-venv
bundle-venv/bin/python -m pip install --upgrade pip

# Door alleen wheel toe te staan, kunnen pakketten die bronbouw vereisen op een offline server vooraf worden ontdekt.
bundle-venv/bin/python -m pip download   --only-binary=:all:   --dest wheelhouse   -r requirements.txt

sha256sum wheelhouse/* > SHA256SUMS
tar -czf python-wheelhouse.tar.gz wheelhouse requirements.txt SHA256SUMS
sha256sum python-wheelhouse.tar.gz > python-wheelhouse.tar.gz.sha256

Verifiëren en installeren op een offline server

sha256sum -c python-wheelhouse.tar.gz.sha256
tar -xzf python-wheelhouse.tar.gz

sha256sum -c SHA256SUMS

python3 -m venv .venv
.venv/bin/python -m pip install   --no-index   --find-links=wheelhouse   -r requirements.txt
.venv/bin/python -m pip check

Als een pakket faalt bij --only-binary=:all:, betekent dit dat er geen compatibele wheel beschikbaar is. In dat geval moet u op een online build-server de benodigde compilers en development headers gebruiken om een wheel te maken, en vervolgens de installatie en uitvoering verifiëren door een nieuwe omgeving aan te maken op een testserver met identieke condities.

Python venv gebruiken in een systemd-service

Aangezien systemd geen interactieve shell is, is het niet nodig om source .venv/bin/activate uit te voeren. Specificeer het absolute pad naar Python in ExecStart en beheer gevoelige informatie in bestanden met beperkte rechten die gescheiden zijn van de broncode.

# /etc/systemd/system/sample-app.service
[Unit]
Description=Sample Python application
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=sampleapp
Group=sampleapp
WorkingDirectory=/opt/sample-app
EnvironmentFile=/etc/sample-app/sample-app.env
ExecStart=/opt/sample-app/.venv/bin/python /opt/sample-app/app.py
Restart=on-failure
RestartSec=5
NoNewPrivileges=true
PrivateTmp=true

[Install]
WantedBy=multi-user.target

sudo systemd-analyze verify /etc/systemd/system/sample-app.service
sudo systemctl daemon-reload
sudo systemctl enable --now sample-app.service
sudo systemctl status sample-app.service --no-pager
sudo journalctl -u sample-app.service -n 100 --no-pager

Waarom u een Python venv niet moet verplaatsen, maar opnieuw moet aanmaken

De shebang van scripts die in een virtuele omgeving zijn geïnstalleerd, kan het absolute pad naar de interpreter van die omgeving bevatten. Als u de map naar een andere locatie of server kopieert, kan dit pad ongeldig worden; daarom moet de venv zelf niet als distributie-artefact worden behandeld. De officieel aanbevolen methode is om op de nieuwe locatie een nieuwe virtuele omgeving aan te maken en de pakketten opnieuw te installeren via afhankelijkheidsbestanden of een wheelhouse.

# Uitvoeringsvoorwaarden en afhankelijkheden van de bestaande omgeving vastleggen
.venv/bin/python --version
.venv/bin/python -m pip freeze > requirements.txt

# Opnieuw aanmaken op een nieuwe locatie
python3 -m venv /opt/sample-app/.venv
/opt/sample-app/.venv/bin/python -m pip install -r requirements.txt
/opt/sample-app/.venv/bin/python -m pip check

Een Python venv veilig verwijderen

Het verwijderen van een virtuele omgeving is in feite het verwijderen van een map, maar typefouten in variabelen of lege paden kunnen ertoe leiden dat andere gegevens worden gewist. Controleer vóór het verwijderen het absolute pad en pyvenv.cfg, en verifieer of er geen actieve services zijn die deze omgeving gebruiken.

# Dit blok wordt uitgevoerd in een subshell, dus het afbreken hiervan sluit de huidige loginshell niet af.
(
  set -eu
  VENV="$(realpath -e -- .venv)"
  test -d "$VENV" && test -f "$VENV/pyvenv.cfg" || {
    echo '가상환경 디렉터리가 아니므로 중단합니다.' >&2
    exit 1
  }
  case "$VENV" in /|"$HOME"|/opt|/usr|/var)
    echo '삭제할 수 없는 상위 경로입니다.' >&2; exit 1 ;;
  esac
  printf 'delete target: %s\n' "$VENV"
  grep -R --fixed-strings "$VENV" /etc/systemd/system /etc/cron* 2>/dev/null || true
  # Reageer na het controleren van de bovenstaande resultaten en de draaiende services/cron.
  read -r -p '이 경로만 삭제하려면 DELETE 입력: ' answer
  if [ "$answer" != DELETE ]; then
    echo '취소했습니다.'
    exit 0
  fi
  rm -rf -- "$VENV"
)

Bij het vervangen van de virtuele omgeving van een productieservice is het beter om niet direct de bestaande map te verwijderen, maar eerst een nieuwe omgeving op een apart pad aan te maken en te testen voordat u de service overzet. Als er problemen optreden, kunt u terugkeren naar het vorige pad.

Veelvoorkomende problemen en oplossingen

python -c "import sys; print(sys.executable); print(sys.version)"
python -m pip --version
python -m pip list
python -m pip check
python -m site

Selectiecriteria voor venv, virtualenv, pipx en conda

• venv: Geschikt voor het handmatig beheren van projectspecifieke omgevingen met alleen de Python-standaardbibliotheek.
• virtualenv: Overweeg dit als u meer opties voor het aanmaken of ondersteuning voor diverse Python-versies nodig heeft.
• pipx: Geschikt voor het installeren van Python CLI-tools die overal in het systeem moeten kunnen draaien, zoals Black of Ansible Lint, in een omgeving per applicatie.
• conda: Wordt voornamelijk gebruikt in wetenschappelijke en data-omgevingen waar niet alleen Python-pakketten, maar ook native bibliotheken beheerd moeten worden.

Voor algemene server- en ontwikkelomgevingen waar projectafhankelijkheden gescheiden moeten worden, is het gebruik van de standaard Python venv de eenvoudigste aanpak; kies pas voor andere tools wanneer er specifieke vereisten zijn, zoals de distributie van CLI-tools of native afhankelijkheden.

Checklist voor de praktijk

1. Controleer het gewenste Python-uitvoerbare bestand en de versie voordat u de virtuele omgeving aanmaakt.
2. Installeer pakketten met python -m pip en verifieer ze met pip check.
3. Sluit .venv/ uit van versiebeheer en bewaar in plaats daarvan requirements- of lock-bestanden.
4. Gebruik voor productieservices het absolute pad naar de Python-interpreter van de virtuele omgeving in plaats van activatiescripts.
5. Kopieer of verplaats virtuele omgevingen niet, maar maak ze opnieuw aan op de doellocatie.
6. Maak bundels voor afgesloten netwerken (air-gapped) onder identieke OS-, CPU- en Python-condities en verifieer deze met SHA-256.
7. Controleer vóór verwijdering het werkelijke pad, pyvenv.cfg, en of er verwijzingen zijn vanuit services of cron-taken.

Gerelateerde handleidingen

• Handleiding voor het bouwen van een NetBox Podman-bundel voor afgesloten netwerken
• Ansible-gebruik en praktijkvoorbeelden

Officiële referentiedocumentatie

• Officiële Python venv-documentatie
• PyPA: Pakketten installeren met pip en virtuele omgevingen
• Documentatie over herhaalbare installaties met pip
• PyPA: Zelfstandige CLI-tools installeren met pipx

Samenvatting

De essentie van Python venv ligt niet in het activatiecommando zelf, maar in het scheiden van de interpreter en pakketpaden die een project gebruikt, en het beheer van die omgeving op een reproduceerbare manier. Gebruik tijdens de ontwikkeling .venv voor het gemak, en specificeer absolute paden bij automatisering in productie. Door afhankelijkheidsbestanden, uitvoeringscondities, integriteitscontroles en vervangingsprocedures samen te beheren, kunt u stabiel opereren op zowel servers als in afgesloten netwerken.