cd

Updated

September 4, 2026

Overview

cd (change directory) sets the shell’s current working directory. It is a shell builtin, not an external program — each shell (bash, zsh, dash) implements it. Directory changes never affect other already-running processes; only the current shell (and its children) see the new cwd.

Syntax

cd [-L|[-P [-e]] [-@]] [directory]
cd -

Common Options / operands

Option / form Description
-L Follow logical path (default); retain symlink components
-P Physical structure; resolve symlinks when determining path
-e With -P, exit non-zero if physical path cannot be determined
- Switch to previous directory ($OLDPWD)
~ or empty Home directory ($HOME)
~user Home of user
.. / . Parent / current
-- End of options (path starts with -)

Key Use Cases

  1. Navigate the filesystem in interactive shells
  2. Anchor scripts to a known directory
  3. Toggle between two locations with cd -
  4. Control symlink resolution (-L vs -P)
  5. Combine with pushd/popd for a directory stack

Examples with Explanations

Basic navigation

cd /usr/local/bin
cd /var/log
cd ~
cd                        # also home
cd ..
cd ../..

Previous directory

cd /etc
cd /var/log
cd -                      # back to /etc
cd -                      # toggle again

$OLDPWD holds the previous directory; cd - prints the new path in many shells.

Paths that start with a dash

mkdir -- -weird
cd -- -weird

Script: run relative to script location

#!/usr/bin/env bash
set -euo pipefail
cd "$(dirname "$(readlink -f "$0")")"
pwd
# now relative paths are stable regardless of caller cwd

Script: require a directory

cd /srv/app || { echo "missing /srv/app" >&2; exit 1; }

pushd / popd alternative workflow

pushd /var/log
pushd /etc/systemd/system
dirs -v
popd
popd

cd alone does not maintain a stack; use pushd/popd when you need one.

One-liners

cd /usr/local/bin && pwd
cd ~alice
cd "$(dirname "$(realpath ./config.yml)")"
cd "$(mktemp -d)"         # disposable workspace

Understanding success and failure

  • Success: no output (except cd - often prints the path).
  • Common errors: permission denied, no such file, not a directory, deleted cwd.
  • Exit status is non-zero on failure — always check in scripts (cd dir || exit 1).

Notes / Pitfalls

  • cd in a subshell does not change the parent: (cd /tmp); pwd still shows the old path.
  • Aliases like alias cd='cd -P' change defaults for interactive use only.
  • CDPATH (if set) makes cd some search a list of base directories — surprising in scripts; unset or avoid relying on it in portable scripts.
  • Broken symlinks and removed directories: physical cd -P fails more honestly.
  • zsh auto-cd (typing a directory name) is a shell feature, not POSIX cd.

2026-relevant notes

  • Containers and distroboxes: know whether you are on the host or in a named mount namespace before bulk relative operations.
  • Network homes ($HOME on NFS) make frequent cd across mounts latency-sensitive; stay local when compiling.
  • Prefer explicit absolute anchors in automation (cd /opt/app) over long chains of cd ...

Additional Resources