Blog

So installieren Sie Python-Pakete aus einer internen Paketregistrierung mit uv

Timo Uelen

Aktualisiert Oktober 14, 2025

4 Minuten

Wenn Sie ein Python-Paket in einem privaten Index veröffentlicht haben, möchten Sie, dass Ihre Benutzer es installieren können. Dazu müssen Sie jedoch etwas einrichten. In diesem Blogpost zeigen wir Ihnen, wie Sie eine interne Paketabhängigkeit mit uv einrichten.

Für unseren Index werden wir die Paketregistrierung von Gitlab verwenden. Aber viele dieser Schritte gelten auch, wenn Sie einen anderen Index verwenden.

Installieren Sie uv

Sie können uv auf verschiedene Arten installieren. Wenn Sie bereits Python haben, können Sie pipx verwenden: 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.

Hinzufügen eines Python-Pakets zu Ihrer Gitlab-Paketregistrierung

Um ein Python-Paket in Ihrer Gitlab-Paketregistrierung zu veröffentlichen, folgen Sie den Schritten in unserem anderen Blogpost. Wenn Sie ein Paket veröffentlicht haben, können Sie mit dem nächsten Schritt fortfahren.

Einrichten Ihrer Anmeldedaten

Erstellen Sie ein persönliches Zugangstoken (für Gitlab)

Um unser internes Paket zu installieren, müssen wir unsere Anmeldedaten konfigurieren. Diese Anweisungen sind spezifisch für Gitlab. Wenn Sie einen anderen Index verwenden, können diese Anweisungen abweichen.

Für die Installation von Paketen verwenden wir ein Personal Access Token. Der Einfachheit halber verwenden Sie die folgende URL und aktualisieren GITLAB_HOST, um Ihren eigenen Gitlab-Host wiederzugeben:

Wenn Sie gitlab.com verwenden, benutzen Sie diese URL: https://gitlab.com/-/user_settings/personal_access_tokens?name=Package+Registry+Token&scopes=api,read_user,read_registry
Wenn Sie eine private Gitlab-Instanz verwenden, benutzen Sie: https://<GITLAB_HOST>/-/user_settings/personal_access_tokens?name=Package+Registry+Token&scopes=api,read_user,read_registry

Diese URL füllt das Formular mit einem Namen und den erforderlichen Berechtigungen. Öffnen Sie es in Ihrem Browser. Klicken Sie auf Persönliches Zugangstoken erstellen und speichern Sie Ihr Token an einem sicheren Ort (z.B. in einem Passwortmanager). Sie werden es im nächsten Schritt benötigen.

Beachten Sie, dass Sie möglicherweise das Ablaufdatum für Ihren Token ändern möchten.

Als Nächstes müssen wir uv über unsere Anmeldedaten informieren.

Speichern von Anmeldeinformationen auf Ihrem System

Wir könnten uv jedes Mal unsere Anmeldedaten mitteilen, wenn wir von unserer privaten Registrierung aus installieren möchten. Aber das wird schnell lästig. Deshalb möchten wir unsere Anmeldeinformationen auf unserem System speichern.

uv unterstützt die Verwendung eines .netrc Datei. In dieser Datei können wir die Anmeldedaten pro Rechner angeben. So können wir die Anmeldeinformationen für einen bestimmten Host nur einmal festlegen.

Erstellen Sie in Ihrem Home-Verzeichnis eine Datei namens .netrc:

touch ~/.netrc

Geben Sie in der Datei Folgendes ein und ändern Sie die Werte für machine und password:

machine myorganization.gitlab.host
login __token__
password <your_token>

Nun ist es an der Zeit, unser internes Paket als Abhängigkeit hinzuzufügen.

Fügen Sie das interne Paket aus dem privaten Index als Abhängigkeit hinzu

Bestimmen Sie Ihre Paketindex-URL

Zunächst müssen Sie Ihre Index-URL festlegen. Um die URL zu erstellen, müssen Sie Ihren Host (z.B. mycompany.gitlab.host) und die Projekt-ID ermitteln.

Sie finden die Projekt-ID auf der Seite Ihres Repositorys.

Gitlab-Projekt-ID

Beachten Sie, dass wir in diesem Blog-Beitrag eine Veröffentlichung in einer Projektpaketregistrierung vornehmen. Es ist aber auch möglich, die Pakete in einer Gruppe oder Organisation zu veröffentlichen. Weitere Informationen dazu finden Sie in den Gitlab-Dokumenten.

Fügen Sie Ihre Abhängigkeit mit uv hinzu

Wir können nun unser internes Paket hinzufügen. Dazu führen wir den Befehl uv add aus und geben den Index an. Wir geben diesem Index auch einen Namen, so dass er --index name=url wird.

Wenn Sie gitlab.com verwenden: uv add my-internal-package --index gitlab=https://gitlab.com/api/v4/projects/PROJECT_ID/packages/pypi/simple
Wenn Sie eine private Gitlab-Instanz verwenden: uv add my-internal-package --index gitlab=https://myorganization.gitlab.host/api/v4/projects/PROJECT_ID/packages/pypi/simple

Dieser Befehl stellt sicher, dass my-internal-package nur aus dem Index namens gitlab installiert wird. Dies verhindert ein Sicherheitsproblem, bei dem ein Paket mit genau demselben Namen von PyPi installiert wird.

Fehler beseitigen

Wenn Sie eine Fehlermeldung erhalten, sollten Sie überprüfen, ob Sie alles richtig ausgefüllt haben. Sie können uv im ausführlichen Modus ausführen, indem Sie -v zu Ihrem Befehl hinzufügen. Dadurch werden mehr Informationen angezeigt. Suchen Sie dann nach Zeilen, die netrc enthalten, wie diese:

DEBUG Checking netrc for credentials for https://myorganization.gitlab.host/api/v4/...
DEBUG Found credentials in netrc file for https://myorganization.gitlab.host/api/v4/...

Was hat sich in pyproject.toml geändert?

Wenn Ihr Befehl erfolgreich war, hat uv die pyproject.toml automatisch aktualisiert. Sie wird nun etwa so aussehen:

dependencies = [
 "my-internal-package==1.0.0",
]

# Lock my-internal-package to our GitLab package registry
[tool.uv.sources]
my-internal-package = { index = "gitlab" }

# Specify where our Gitlab package registry is
[[tool.uv.index]]
name = "gitlab"
url = "https://<GITLAB_HOST>/api/v4/projects/<PROJECT_ID>/packages/pypi/simple"

Fazit

In diesem Blogpost haben wir:

Legen Sie die Zugangsdaten für unseren privaten Index in einer .netrc Datei an, damit sie wiederverwendet werden können.
Ein internes Paket zu unseren Projektabhängigkeiten hinzugefügt.
Wir haben uv angewiesen, nur nach unserem internen Paket in unserem privaten Index zu suchen.

Diese Schritte werden die Einführung von uv in Ihrem Unternehmen hoffentlich erleichtern.