zsh am Mac: PATH, Aliase und „command not found“

Du installierst ein Programm, tippst seinen Namen ins Terminal und bekommst zsh: command not found. Oder brew funktioniert in einem Fenster, im nächsten aber nicht. Oder python3 startet eine andere Version als die, die Du gerade installiert hast. Hinter all diesen Fehlern steckt dasselbe: der PATH, also die Liste der Ordner, in denen die Shell nach Befehlen sucht, und die Frage, in welcher Startdatei er gesetzt wird.

Diese Anleitung erklärt Dir, wie die zsh am Mac Befehle findet, welche Startdatei wann geladen wird und warum ein Eintrag manchmal an der falschen Stelle landet. Danach erweiterst Du den PATH dauerhaft und richtest Aliase ein. Getestet habe ich alle Befehle unter macOS 27.2 mit zsh 5.9 und Homebrew 7 auf einem Mac mit Apple-Chip.

Wie die Shell einen Befehl findet

Wenn Du brew eintippst, schaut die zsh zuerst, ob es einen Alias, eine Funktion oder einen eingebauten Befehl mit diesem Namen gibt. Ist das nicht der Fall, geht sie die Ordner im PATH von links nach rechts durch und startet die erste ausführbare Datei, die so heißt. Findet sie in keinem Ordner etwas, meldet sie command not found.

Den aktuellen PATH siehst Du übersichtlich, einen Ordner pro Zeile, mit:

echo $PATH | tr ':' '\n'

Auf einem Mac mit Homebrew sieht der Anfang typischerweise so aus:

/opt/homebrew/bin
/opt/homebrew/sbin
/usr/local/bin
/System/Cryptexes/App/usr/bin
/usr/bin
/bin
/usr/sbin
/sbin

Die Reihenfolge ist entscheidend. Liegt python3 sowohl in /opt/homebrew/bin als auch in /usr/bin, gewinnt der Ordner, der weiter oben steht. Welche Kopien eines Befehls es gibt und welche zuerst gefunden wird, zeigt Dir:

which -a python3

Die erste Zeile der Ausgabe ist die Version, die tatsächlich startet. Steht dort eine andere als erwartet, stimmt die Reihenfolge im PATH nicht.

Die Startdateien und wann welche lädt

Die zsh liest beim Start mehrere Dateien in fester Reihenfolge. Die systemweiten unter /etc gehören macOS, die in Deinem Benutzerordner gehören Dir:

Eine Besonderheit am Mac: Die App Terminal startet jedes neue Fenster als Login-Shell. Es werden also bei jedem neuen Fenster sowohl ~/.zprofile als auch ~/.zshrc gelesen. Die genaue Logik beschreibt die zsh-Dokumentation zu den Startdateien.

path_helper: der Grund für die meisten Rätsel

In /etc/zprofile steht am Mac dieser Block:

if [ -x /usr/libexec/path_helper ]; then
	eval `/usr/libexec/path_helper -s`
fi

Das Programm path_helper baut den PATH bei jeder Login-Shell neu zusammen. Es liest die Systemordner aus der Datei /etc/paths und aus den Dateien in /etc/paths.d und stellt sie an den Anfang. Alles, was vorher schon im PATH stand, hängt es hinten an.

Das hat eine Folge, die viele überrascht: Setzt Du Deinen PATH in ~/.zshenv, läuft diese Datei vor /etc/zprofile, und path_helper schiebt Deinen Eintrag danach hinter die Systemordner. Ich habe das getestet: Ein Ordner, der in ~/.zshenv an erster Stelle stand, landete nach dem Start eines Login-Fensters auf Position 13. Dein selbst installiertes python3 verliert dann gegen das von Apple, obwohl Du alles richtig eingetragen hast.

Die Regel daraus ist einfach: PATH-Änderungen gehören in ~/.zprofile oder ~/.zshrc, beide laufen nach path_helper. Nie in ~/.zshenv.

Homebrew auf Macs mit Apple-Chip

Homebrew installiert sich auf Macs mit Apple-Chip nach /opt/homebrew, und dieser Ordner steht nicht in /etc/paths. Deshalb meldet das Terminal nach der Installation zsh: command not found: brew, bis Du ihn einträgst. Das Installationsskript nennt die nötigen Befehle am Ende, und die Homebrew-Doku zur Installation beschreibt sie ebenfalls:

echo >> ~/.zprofile
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"

Die erste Zeile hängt eine Leerzeile an ~/.zprofile an, die zweite den Befehl, der bei jedem Start die Homebrew-Ordner vorn in den PATH setzt. Die dritte führt ihn sofort im aktuellen Fenster aus, damit Du nicht neu starten musst. Prüf danach mit brew --version, ob es klappt. Die vollständige Installation zeigt Homebrew auf dem Mac installieren: Anleitung für macOS 27.

Auf Intel-Macs liegt Homebrew unter /usr/local, das schon in /etc/paths steht. Dort brauchst Du diesen Schritt nicht.

PATH dauerhaft erweitern

Willst Du einen eigenen Ordner in den PATH aufnehmen, etwa ~/.local/bin für Programme, die Python-Werkzeuge wie pipx dort ablegen, öffnest Du ~/.zshrc im Editor:

nano ~/.zshrc

Existiert die Datei noch nicht, legt nano sie an. Füge diese Zeilen ein:

typeset -U path
path=("$HOME/.local/bin" $path)

Die erste Zeile sorgt dafür, dass jeder Ordner nur einmal im PATH steht, auch wenn die Datei mehrmals geladen wird. Die zweite stellt ~/.local/bin an den Anfang. Die zsh hält den PATH zusätzlich als Liste in der Kleinbuchstaben-Variable path vor, und Änderungen daran landen automatisch im großgeschriebenen PATH. Das ist übersichtlicher als das Zusammenkleben mit Doppelpunkten.

Speichere mit Ctrl + O, bestätige mit Enter und schließe den Editor mit Ctrl + X.

Soll ein Ordner hinten angehängt werden, damit er die Systemprogramme nicht überdeckt, schreibst Du ihn ans Ende: path=($path "$HOME/tools").

Aliase und kleine Funktionen

Aliase sind Abkürzungen für Befehle, die Du oft tippst. Sie gehören ebenfalls in ~/.zshrc. Eine aufgeräumte Datei mit PATH, Aliasen und einer kleinen Funktion sieht etwa so aus:

# Doppelte PATH-Einträge automatisch entfernen
typeset -U path

# Eigene Programme vorne in den PATH
path=("$HOME/.local/bin" "$HOME/bin" $path)

# Aliase
alias ll='ls -lAh'
alias ..='cd ..'
alias gs='git status'

# Kleine Funktion: Ordner anlegen und hineinwechseln
mkcd() {
  mkdir -p "$1" && cd "$1"
}

ll zeigt alle Dateien mit Größe und Rechten, .. wechselt eine Ebene höher, gs zeigt den Git-Status. Die Funktion mkcd projekt legt den Ordner projekt an und wechselt hinein. Aliase taugen nur für feste Befehle, sobald ein Argument in der Mitte stehen muss, nimmst Du eine Funktion wie mkcd. Die Datei habe ich in genau dieser Form mit zsh -n auf Syntaxfehler geprüft und in einer frischen Shell getestet.

Änderungen übernehmen

Eine geänderte ~/.zshrc wirkt erst in neuen Terminalfenstern. Im aktuellen Fenster lädst Du sie mit:

source ~/.zshrc

Hast Du ~/.zprofile geändert, öffnest Du am einfachsten ein neues Fenster mit Cmd + N. Ob ein Alias oder eine Funktion angekommen ist, zeigt whence -v ll. Die Antwort lautet dann zum Beispiel ll is an alias for ls -lAh.

Wurde ein Programm gerade erst installiert und die Shell findet es trotzdem nicht, obwohl der Ordner im PATH steht, liegt das manchmal am Befehlscache der zsh. Den leerst Du mit rehash.

Typische Fehler und ihre Lösung

command not found direkt nach einer Installation. Das Terminalfenster war schon vor der Installation offen, oder die Homebrew-Zeile fehlt in ~/.zprofile. Öffne ein neues Fenster. Hilft das nicht, prüf mit cat ~/.zprofile, ob die brew shellenv-Zeile darin steht.

Ein Programm startet in der falschen Version. which -a <programm> zeigt alle Kopien. Steht die gewünschte nicht oben, setz ihren Ordner in ~/.zprofile oder ~/.zshrc an den Anfang des PATH, nicht in ~/.zshenv.

Der PATH wird immer länger und enthält Ordner doppelt. Jemand hängt mit export PATH="...:$PATH" bei jedem Laden der Datei neu an, etwa durch wiederholtes source ~/.zshrc. typeset -U path am Anfang der ~/.zshrc beendet das.

Einstellungen aus .bash_profile wirken nicht. Seit macOS Catalina ist die zsh die Standard-Shell, wie Apple im Artikel zsh als Standard-Shell auf dem Mac verwenden beschreibt. Die zsh liest ~/.bash_profile und ~/.bashrc nicht. Übertrag die Zeilen, die Du noch brauchst, in ~/.zprofile (PATH und Variablen) oder ~/.zshrc (Aliase), und prüf dabei, ob sie noch aktuell sind. Viele stammen aus Zeiten von Intel-Macs.

Nach einem Tippfehler in der .zshrc startet das Terminal mit Fehlermeldungen. Die Shell lädt trotzdem, meldet aber die fehlerhafte Zeile mit Nummer, zum Beispiel /Users/name/.zshrc:12: parse error. Öffne die Datei mit nano ~/.zshrc, spring mit Ctrl + _ und der Zeilennummer zur Stelle und korrigiere sie.

Fazit

Die meisten PATH-Probleme am Mac lösen sich mit drei Regeln: Homebrew gehört per brew shellenv in ~/.zprofile, eigene Ordner und Aliase gehören in ~/.zshrc, und ~/.zshenv lässt Du für den PATH in Ruhe, weil path_helper ihn danach umsortiert. Mit which -a und echo $PATH | tr ':' '\n' siehst Du jederzeit, was die Shell gerade wirklich tut. Wenn Du Deinen Mac gleich komplett als Entwicklungsrechner einrichten willst, inklusive Git, SSH-Schlüssel und Editor, hilft Mac für Entwickler einrichten: der Leitfaden für 2026 weiter.