CD(1)

💿 CD(1) — fish-shell's cd, bestie edition ✨

okay so real talk, this page is about the fish builtin cd 💅 — like, the fish-shell version specifically. Wanna see the docs for some non-fish cd? go run command man cd instead, no cap.

---

✨ SYNOPSIS ✨

cd [( -L | --no-dereference ) | ( -P | --dereference )] [DIRECTORY]

---

🌸 DESCRIPTION 🌸

cd changes the current working directory. that's it, that's the whole vibe. 🫶

The PWD environment variable gets updated with your new working directory, and the previous directory gets added to the directory history. so nothing is ever really lost, it's giving "no delete, only archive" 💖

• DIRECTORY — if you pass it, it becomes your new directory. if you pass nothing, the HOME environment variable is what gets used. home sweet home, literally 🏠

If DIRECTORY is a relative path, every path in CDPATH gets tried as a prefix for it, in addition to PWD. and like — highly recommend keeping . as the first element of CDPATH, otherwise PWD gets tried last. consider this your friendly reminder 🎀

The new directory name is partially resolved to remove redundant segments (. or ..). we love a tidy path ✨

cd defaults to treating symbolic links as real directories, and not resolving them to their underlying targets. the $PWD special variable will contain the path that was supplied. this default behaviour can be enforced with the -L or --no-dereference option. slay, keep your symlinks as symlinks 💅

🦋 the dereference options

• -L, --no-dereference — enforce the default: treat symbolic links as real directories, don't resolve them to their targets. $PWD keeps the path you supplied 💜
• -P, --dereference — resolves all symbolic links first. important lore: this was the default in fish versions before 3.0.0 😭
• -h, --help — displays help about using this command and does not change the directory. literally just reads the group chat, doesn't reply 🙈

⭐ other iconic behaviours

fish will also try to change directory if you give it a command that looks like a directory — starting with ., / or ~, or ending with / — without explicitly requiring cd. it just knows. iykyk 🧚

fish also ships a wrapper function around the builtin cd that understands cd - as changing to the previous directory. see also prevd. this wrapper function maintains a history of the 25 most recently visited directories in the $dirprev and $dirnext global variables. and like — if you make those universal variables, your cd history is shared among all fish instances. main character energy for your whole terminal 🌈👑

as a special case, cd . is equivalent to cd $PWD, which is genuinely useful in cases where a mountpoint has been recycled or a directory has been removed and recreated. lowkey a lifesaver 🔥

---

🎀 EXAMPLES 🎀

cd
# changes the working directory to your home directory.

cd /usr/src/fish-shell
# changes the working directory to /usr/src/fish-shell

cd -P /tmp/link
# resolves /tmp/link to its target before recording the directory

---

💖 SEE ALSO 💖

• Navigate directories using the directory history or the directory stack 🌸

---

👑 Copyright 👑

fish-shell developers — respect the icons 🫡

---

okay bestie that's the whole page, go forth and cd responsibly 💅✨

sign-off time: this lil doc is from the fish-shell fam, version 4.9, dated Sep 08, 2026 — screenshot it, quote it, live by it 🎀🦋💜