Blog

So veröffentlichen Sie ein Python-Paket in einer Gitlab-Paketregistrierung mit uv

Timo Uelen

Aktualisiert Oktober 15, 2025

5 Minuten

In vielen Unternehmen besteht ein Bedarf an internen Paketen. Die Installation dieser Pakete ist oft schwierig. Um dies zu erleichtern, können Sie eine interne Paketregistrierung verwenden. Gitlab bietet diese Funktion standardmäßig an. Wir zeigen Ihnen, wie Sie mit uv, einem schnellen Python-Paketmanager, in diesen Index deployen können.

Warum uv?

Wir können uv aus den folgenden Gründen empfehlen:

Es ist extrem schnell bei der Auflösung von Abhängigkeiten und deren Installation. Das macht die Entwicklung und die Builds schneller, was großartig ist.
Es verwaltet virtuelle Umgebungen für Sie.
Es kann Python-Versionen für Sie verwalten. Damit entfällt die Notwendigkeit von Conda, pyenv oder der manuellen Installation von Python.
Es basiert auf Standards wie der pyproject.toml Spezifikation.

Für weitere Vorteile können Sie das uv Repository besuchen.

Installieren wir es!

Installieren Sie uv

Sie können uv auf verschiedene Arten installieren. Wenn Sie bereits über Python verfügen, können Sie pipx verwenden. pipx kann Programme getrennt von anderen Python-Umgebungen installieren: pipx install uv.

Wenn Sie es als Einzelplatzversion installieren möchten, können Sie curl verwenden:

curl -LsSf https://astral.sh/uv/install.sh | sh

Weitere Anleitungen finden Sie im uv-Repository.

Erstellen Sie ein neues Gitlab-Repository

Hinweis: Wenn Sie ein bestehendes Repository haben, können Sie diesen Schritt überspringen. Ihr Projekt muss aber trotzdem mit uv eingerichtet werden.

Erstellen Sie auf Gitlab über die Schaltfläche + ein neues Repository und gehen Sie die einzelnen Schritte durch.

Klonen Sie das Repository auf Ihren Computer: Klicken Sie auf die blaue Schaltfläche "Code" und führen Sie die Schritte aus. Möglicherweise müssen Sie zuerst die Authentifizierung einrichten.
Sobald Sie geklont sind, gehen Sie unter cd in das Projektverzeichnis und führen Sie uv init --package . Damit wird das Projekt eingerichtet. Wir verwenden die Flagge --package, weil wir unseren Code als Paket weitergeben wollen!
Erstellen Sie einen Git-Commit: git add . und git commit -m "Init package"
Schließlich pushen Sie es in unser Repository: git push.

Unser Paket ist jetzt bereit zur Veröffentlichung. Aber es ist noch nicht veröffentlicht. Lassen Sie uns eine Pipeline zur Veröffentlichung unseres Pakets erstellen!

Erstellen Sie Ihre Gitlab CI-Pipeline

Erstellen Sie in Ihrem Projektverzeichnis eine Datei namens .gitlab-ci.yml. In dieser Datei teilen wir Gitlab mit, wie unsere CI-Pipeline aussehen wird. Wir werden Git-Tags verwenden, um unsere Versionsnummer zu bestimmen.

Kopieren Sie den folgenden Inhalt in die Datei:

# We can define multiple stages here, but for this example we have only one. What happens in the publish stage is defined later.
stages:  
  - publish  

variables:  
  PYTHON_VERSION: "3.13"  
  UV_VERSION: "0.5.5"  
  # With the following variables, we tell uv how to publish our package.
  # Gitlab has built in usernames and passwords for publish packages. This means you don't need to change them!
  UV_PUBLISH_URL: "${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/pypi"  
  UV_PUBLISH_USERNAME: "gitlab-ci-token"  
  UV_PUBLISH_PASSWORD: "${CI_JOB_TOKEN}"  

# Before we do anything else, we need to install uv
before_script:  
  - pip install uv==${UV_VERSION}  # pipx is not needed on Gitlab, because we use a fresh environment every run

# This stage publishes to our Gitlab package registry
publish:  
  stage: publish  
  image: python:${PYTHON_VERSION}
  script:  
    # Set the version in pyproject.toml to the current git tag  
    - VERSION=$(git describe --exact-match --tags)  
    - uvx --from=toml-cli toml set --toml-path=pyproject.toml project.version $VERSION  
    # Build and publish the package  
    - uv build  
    - uv publish dist/*.whl  
  only:  # Only run this stage when a tag is created/pushed
    - tags

Erläuterung der Definition der CI-Pipeline

Variablen

In der variables definieren wir Variablen, die an einer Stelle gesetzt und wiederverwendet werden können. Dies ist hilfreich, wenn Sie die Pipeline erweitern, daher ist es gut, sie von Anfang an einzurichten.

Phase veröffentlichen

In dieser Phase publish wird unser Paket in der Paketregistrierung veröffentlicht. Dies umfasst eine Reihe von verschiedenen Schritten:

Holen Sie die Versionsnummer aus dem letzten Git-Tag.
Ändern Sie die Versionsnummer in pyproject.toml auf den neuesten Git-Tag. Zum Zeitpunkt der Erstellung dieses Artikels unterstützt uv (noch) keine dynamische Versionierung. Weitere Informationen finden Sie in dieser Ausgabe.
Erstellen Sie unser Projekt. Dadurch wird ein Verzeichnis dist erstellt, das unser gebautes Paket enthält.
Veröffentlichen Sie das Paket in der Registry, die wir in den Variablen definiert haben. Dadurch wird nur das whl Datei, die sich im Verzeichnis dist befindet. whl ist viel schneller zu installieren, da es nicht von Grund auf neu erstellt werden muss (wie .tar.gz).

Commit, Tag und Push Ihrer CI-Pipeline

Übertragen Sie zunächst unsere neue Pipeline:

git add .gitlab-ci.yml
git commit -m "Add pipeline to publish our package"

Erstellen Sie dann ein Git-Tag und geben Sie Ihre Versionsnummer an. Beachten Sie, dass das Tag nicht bereits existieren darf, sonst wird ein Fehler ausgegeben.

git tag 0.0.1

Pushen Sie nun den Commit und das Tag in unser Gitlab-Repository:

git push --tags

Unsere Pipeline wird automatisch bei Tags ausgelöst. Das heißt, sie sollte bereits laufen! Um den Fortschritt zu sehen, gehen Sie zu Ihrem Repository auf Gitlab und wählen Sie Build > Pipelines in der Seitenleiste:

Wenn alles gut gegangen ist, sollten Sie "Bestanden" in grün sehen. Wenn ein Fehler aufgetreten ist, untersuchen Sie ihn, indem Sie auf "Fehlgeschlagen" klicken und die Protokolle sorgfältig lesen. Wenden Sie dann die entsprechenden Korrekturen an.

Wenn dies erfolgreich war, können wir unser veröffentlichtes Paket unter Deploy > Package Registry einsehen:

Fazit

In diesem Blogpost haben wir:

Erstellen Sie ein Python-Paket mit uv
Eine Gitlab CI-Pipeline erstellt
Ein Paket wurde erfolgreich in einer internen Paketregistrierung veröffentlicht.

Jetzt können die Benutzer mit der Installation unseres Pakets beginnen!