Met uv vastleggen, installeren en uitvoeren

Je collega gebruikt dezelfde projectbeschrijving, maar krijgt na een installatie andere pakketversies. Het gewenste bereik en de gekozen versies zijn verschillende afspraken. Leg de gemaakte keuzes vast en controleer ze voordat je een programma start.

Van afspraak naar vastgelegde keuze

Je kent pyproject.toml als beschrijving van het project. Een lockfile legt vast welke pakketversies en bronnen een gereedschap daarvoor heeft gekozen. Met uv schrijf je die gegevens naar uv.lock.

Je bewerkt de projectbeschrijving bewust; laat uv de lockfile genereren. Bewaar beide bestanden bij je broncode, zodat een collega dezelfde vastgelegde keuzes kan gebruiken. Een bestaande lockfile zegt nog niet dat de pakketten al in een omgeving geïnstalleerd zijn.

In deze oefening staat uv 0.13.6 klaar. Het kleine project trip-kit heeft geen externe uitvoerafhankelijkheden en de bouwbackend is al beschikbaar. Daardoor kunnen de werkelijke opdrachten met --offline werken, zonder pakketten te downloaden.

Het eerste voorbeeld gebruikt een ander project en leest de werkelijk gegenereerde lockfile. Zelfs zonder externe afhankelijkheden bevat die een record voor het eigen project. De uitvoer is dus afkomstig uit een bestand dat uv net geschreven heeft.

[project]
name = "map-kit"
version = "0.1.0"
requires-python = ">=3.14,<3.15"
dependencies = []

[project.scripts]
map-report = "map_kit:main"

[build-system]
requires = ["uv_build==0.13.6"]
build-backend = "uv_build"

3.14.2

def main():
    print("Kaart klaar.")
    return 0

import subprocess
import tomllib
from pathlib import Path

subprocess.run(["uv", "--quiet", "lock", "--offline"], check=True)
locked = tomllib.loads(Path("uv.lock").read_text())
for package in locked["package"]:
    print(package["name"], package["version"])

map-kit 0.1.0

De omgeving laten aansluiten

Synchroniseren betekent dat uv de projectomgeving laat aansluiten op de lockfile. uv sync --locked --offline maakt of gebruikt de omgeving en installeert hier ook het eigen project. De meegeleverde build-system-tabel vertelt hoe dat project gebouwd wordt.

De optie --locked vraagt om een actuele lockfile. Kloppen de projectafspraken er niet meer bij, dan stopt uv met een fout in plaats van de lockfile stilzwijgend bij te werken. Dat is bruikbaar wanneer je wilt controleren wat een collega heeft vastgelegd.

In de vorige les koos je zelf het interpreterpad. Hier beheert uv de omgeving bij het project. De meegeleverde .python-version noemt Python 3.14.2; die interpreter is in deze oefenomgeving al aanwezig.

uv lock --offline
uv sync --locked --offline

Het geïnstalleerde commando starten

Met uv run --locked --offline trip-report "$@" start je de meegeleverde console-ingang. Zonder --locked kan uv bij uitvoeren eerst opnieuw locken. Gebruik de optie hier bewust, zodat een ontbrekende of verouderde afspraak zichtbaar wordt.

De commandonaam komt uit project.scripts, dat je eerder hebt ingevuld. De tekst achter de dubbele punt verwijst naar een functie in het geïnstalleerde pakket. De ontvangen argumenten geef je net als in de venv-les met "$@" door.

Veelgemaakte fout: controleren door opnieuw te genereren

Na een projectwijziging is uv lock een opdracht om de keuzes opnieuw vast te leggen. Dat is niet hetzelfde als controleren of de oude lockfile nog past. Voor die controle gebruik je uv lock --check --offline.

Het tweede voorbeeld genereert eerst een geldige lockfile en verandert daarna de projectversie. De echte controle weigert vervolgens verder te gaan. Dat is nuttige feedback: beslis bewust of de projectwijziging klopt en genereer daarna zo nodig opnieuw.

[project]
name = "map-kit"
version = "0.1.0"
requires-python = ">=3.14,<3.15"
dependencies = []

[project.scripts]
map-report = "map_kit:main"

[build-system]
requires = ["uv_build==0.13.6"]
build-backend = "uv_build"

3.14.2

def main():
    print("Kaart klaar.")
    return 0

import subprocess
from pathlib import Path

subprocess.run(["uv", "--quiet", "lock", "--offline"], check=True)
project = Path("pyproject.toml")
project.write_text(project.read_text().replace('version = "0.1.0"', 'version = "0.2.0"'))
checked = subprocess.run(["uv", "--quiet", "lock", "--check", "--offline"])
raise SystemExit(checked.returncode)

lockfile

In de opdracht zijn de vier commandobestanden afzonderlijke stappen. De meegeleverde controle regelt de volgorde en probeert ook een verouderde projectbeschrijving. Zelf verzonnen uitvoer of altijd succes teruggeven vervangt die handelingen niet.

Onthoud dit

• De projectbeschrijving en de gegenereerde lockfile hebben verschillende rollen.
• Synchroniseren installeert de vastgelegde projectomgeving.
• locked en check maken een verouderde afspraak zichtbaar.

Hierna onderzoek je wanneer de standaardbibliotheek voldoende is en wanneer een project een afhankelijkheid nodig heeft.