.gitignore für Python: was rein gehört und was nicht

Die .gitignore ist eine Textdatei im Projektordner. Darin steht, was Git nicht ins Repository übernimmt. In Python-Projekten ist das vor allem die virtuelle Umgebung, dazu Cache-Ordner und Dateien, die nur auf deinen Rechner gehören. Meine venv habe ich am Anfang mit hochgeladen, weil sie in keiner .gitignore stand.

Wie du eine venv anlegst und wofür sie gut ist, steht in meinem Beitrag zu Python venv.

Was in die .gitignore für Python gehört

So sieht eine .gitignore für ein kleines Python-Projekt aus:

# virtuelle Umgebung
.venv/

# Cache von Python
__pycache__/

# Zugangsdaten und Schlüssel
.env

# macOS
.DS_Store

# Beispieldateien, nur für mich
beispieldateien/

Jede Zeile ist ein Muster. Steht am Ende ein /, passt es nur auf Ordner. Zeilen mit # am Anfang sind Kommentare. Alle Regeln stehen in der Git-Doku zu gitignore (öffnet in neuem Tab).

• .venv/ ist die virtuelle Umgebung. Eine frische venv mit Python 3.14.4 hat schon fast 900 Dateien. Ins Repository kommt stattdessen die requirements.txt, aus der sich jeder die venv selbst baut.
• __pycache__/ legt Python an, sobald du ein eigenes Modul importierst. Darin liegt übersetzter Code, den Python jederzeit neu erzeugt (Python-Doku zu __pycache__ (öffnet in neuem Tab)).
• .env ist eine übliche Datei für Zugangsdaten und API-Schlüssel. Die haben auf GitHub nichts zu suchen.
• .DS_Store legt der Finder auf dem Mac in fast jedem Ordner an. Mit deinem Projekt hat die Datei nichts zu tun.
• Dazu kommt bei mir alles, was meiner Meinung nach nicht auf Git gehört, zum Beispiel Ordner mit Beispieldateien.

.gitignore erstellen

Seit Python 3.13 nimmt dir venv einen Teil ab. Nach python3 -m venv .venv liegt im Ordner .venv eine eigene .gitignore mit nur einer Regel: *. Das Sternchen blendet alles in diesem Ordner aus. Mit Python 3.14.4 auf dem Mac ist die Datei da, und git status zeigt die venv nicht mehr an (Python-Doku zu venv (öffnet in neuem Tab)). Genauso macht es Ruff mit seinem Ordner .ruff_cache, wenn du Ruff im Terminal laufen lässt. Was Ruff sonst prüft, steht in meinem Beitrag zu PEP 8.

Für alles andere lege ich die .gitignore von Hand an. Im Terminal geht das im Projektordner mit diesem Befehl:

touch .gitignore

Danach öffnest du die Datei in VS Code und trägst die Zeilen ein. Unter Windows legst du sie direkt in VS Code als neue Datei an. Die Zeile .venv/ steht bei mir trotzdem drin. Sie greift auch bei einer venv, die mit einer älteren Python-Version angelegt wurde.

Wenn die venv schon im Repository liegt

Mir ist es auf GitHub aufgefallen, als ich mir das Projekt angesehen habe. In VS Code waren außerdem die typischen Git-Symbole an dem Ordner zu sehen. Ich habe die Dateien damals von Hand auf GitHub gelöscht und mir danach angesehen, wie ich sie ausschließe.

Ein neuer Eintrag in der .gitignore wirkt allerdings nicht auf Dateien, die Git schon verfolgt. Für diesen Fall beschreibt die Git-Doku einen Weg, bei dem die venv auf deinem Rechner bleibt:

git rm -r --cached .venv
git add .gitignore
git commit -m "venv aus dem Repository entfernt"
git push

git rm --cached nimmt die Dateien aus Git heraus, lässt sie aber auf der Festplatte. Das -r braucht es, weil .venv ein Ordner ist. Nach dem Push ist die venv auf GitHub weg, und der Eintrag in der .gitignore sorgt dafür, dass sie nicht zurückkommt.

Löschst du die venv nur auf GitHub und holst dir die Änderung danach mit git pull, verschwindet sie auch auf deinem Rechner. Dann legst du sie neu an und installierst die Pakete wieder mit pip install -r requirements.txt.

.gitignore in Godot-Projekten

In Godot gehört der Ordner .godot/ in die .gitignore. Godot speichert dort Cache-Daten des Projekts. Die Datei kann Godot selbst anlegen: Beim Erstellen eines Projekts wählst du unter „Version Control Metadata“ die Option „Git“. Bei einem bestehenden Projekt geht es über „Project > Version Control > Generate Version Control Metadata“. Godot legt dann .gitignore und .gitattributes im Projektordner an, siehe Godot-Doku zur Versionsverwaltung (öffnet in neuem Tab). Meine anderen Beiträge zu Godot findest du unter Godot.

Häufige Fragen

Gehört die .gitignore selbst ins Repository?

Ja. Die .gitignore committest du ganz normal mit. So gelten dieselben Regeln für jeden, der das Projekt klont, und auch für dich auf einem anderen Rechner.

Kann ich mehrere .gitignore-Dateien haben?

Ja. Jeder Ordner im Projekt kann eine eigene .gitignore haben. Ihre Regeln gelten für diesen Ordner und alles darunter. Genau so arbeitet venv: Es legt im Ordner .venv eine eigene .gitignore an.

Fehler gefunden oder eine Frage zum Code? Schreib einen Kommentar oder eine E-Mail.