Guides

pushd, popd and dirs: use the directory stack in bash, zsh and Windows

How pushd, popd and dirs work in bash and zsh: jump with +N and -N, dirs -v, cd - vs pushd, quiet output, use in scripts, plus pushd in cmd and PowerShell.

Published ~7 min read
On this page

Short answer: pushd DIR changes to DIR and puts the directory you came from on a stack; popd takes you back to it. dirs -v lists the stack with numbers, and pushd +N jumps to entry N. All three are bash and zsh builtins, so there is nothing to install.

bash · zsh
pushd /etc/nginx       # go to /etc/nginx, remember where you were
pushd /var/log/nginx   # go on, remember /etc/nginx too
dirs -v                # show the stack with index numbers
popd                   # back to /etc/nginx
popd                   # back to where you started

Every output below comes from bash 5.2.15 on Debian 12, run in a scratch home directory that is shown here as /home/demo. Option meanings are from the bash manual (Directory Stack Builtins) and help pushd.

How the directory stack works

The stack always holds the current directory as entry 0. pushd DIR puts DIR on top, which makes it the new current directory, and prints the whole stack, left to right from the top:

Example output · bash 5.2.15
$ cd ~
$ pushd project/src
~/project/src ~
$ pushd ~/project/logs
~/project/logs ~/project/src ~
$ pushd /tmp
/tmp ~/project/logs ~/project/src ~
$ dirs -v
 0  /tmp
 1  ~/project/logs
 2  ~/project/src
 3  ~

popd removes entry 0 and changes to the new top. pushd with no argument swaps the top two entries, so you can toggle between two directories; with only one entry it fails with pushd: no other directory. Bash keeps duplicates: running pushd /tmp twice leaves /tmp on the stack twice.

Jump with +N and -N

With a number, pushd does not add anything: it rotates the stack until entry N is on top. +N counts from the left of the dirs list, -N from the right, both starting at zero. Continuing the session above:

Example output · bash 5.2.15
$ pushd +2
~/project/src ~ /tmp ~/project/logs
$ pwd
/home/demo/project/src
$ pushd
~ ~/project/src /tmp ~/project/logs
$ popd
~/project/src /tmp ~/project/logs
$ popd +1
~/project/src ~/project/logs

Rotation keeps the order and only moves the start point: after pushd +2, the two entries that were above ~/project/src moved to the bottom. popd +1 removes entry 1 without changing directory, because the current one (entry 0) stays.

CommandEffect
pushd DIRChange to DIR, push the old directory
pushdSwap the top two entries (toggle)
pushd +NRotate so that entry N (from the left) is on top and current
pushd -NSame, counting from the right; pushd -0 brings the bottom entry up
pushd -n DIRAdd DIR as entry 1 without changing directory
popdRemove entry 0 and change to the new top
popd +NRemove entry N only; popd -0 removes the bottom entry
popd -nRemove entry 1, stay where you are
dirs -vOne entry per line with its index
dirs -lFull paths instead of ~
dirs +NPrint entry N only
dirs -cClear the stack (the current directory stays)

The stack is also the array DIRSTACK: cd "${DIRSTACK[2]}" uses an entry in any command, and assigning to an element changes that entry. The bash manual adds that only pushd and popd can add or remove entries, and that assigning does not change the current directory. Unlike dirs, the array holds full paths, never ~.

cd - vs pushd

cd - goes back to the previous directory, which bash keeps in $OLDPWD, and prints it. That is one step of memory, enough for switching between two places. The stack pays off with three or more: a config directory, a log directory and a web root, for example, while you fix a site on a server.

The two meet in entry 0: a plain cd replaces the top of the stack instead of pushing. With ~/project/src and ~/project below the top, cd /tmp turned the stack into /tmp ~/project/src ~/project: the directory you left with cd is gone from it. If you want every move remembered, zsh can do that automatically (below); in bash, use pushd for the moves you want to come back from. For the path itself, pwd prints where you are right now.

Silence pushd and popd

Bash has no quiet option, so redirect the stack listing; error messages still reach the terminal because they go to stderr:

bash
pushd /var/www > /dev/null
popd > /dev/null

# or for every interactive use, in ~/.bashrc:
pushd() { builtin pushd "$@" > /dev/null; }
popd()  { builtin popd "$@" > /dev/null; }
alias d='dirs -v'

builtin makes the function call the real command instead of itself. Put those lines in your ~/.bashrc to have them in every new terminal. In zsh, pushd -q and popd -q are quiet on their own, and setopt pushd_silent makes that the default.

pushd and popd in scripts

The directory stack belongs to one shell process, so a script has its own, starts with an empty one, and cannot change the stack or the directory of the terminal that runs it. A typical use is stepping into folders and back:

loop.sh
#!/bin/bash
set -e
for d in "$HOME"/project/*/; do
  pushd "$d" > /dev/null
  echo "in $(basename "$PWD")"
  popd > /dev/null
done
  • Use bash, not sh. pushd is not part of POSIX sh. On Debian and Ubuntu, /bin/sh is dash, and sh -c 'pushd /tmp' fails with sh: 1: pushd: not found and exit status 127, the command not found code. Start the script with #!/bin/bash and run it as ./loop.sh or bash loop.sh, not sh loop.sh; the guide to running .sh files explains the difference.
  • Check for failure. pushd /nonexistent prints pushd: /nonexistent: No such file or directory and returns 1 without changing anything; popd on an empty stack prints popd: directory stack empty. Without set -e, write pushd "$d" > /dev/null || exit 1 so later commands do not run in the wrong directory.
  • A subshell is often simpler. ( cd "$d" && make ) runs in a child process, so the directory change ends with the parentheses and nothing needs to be undone.

pushd and popd in zsh

zsh has the same three builtins with the same +N/-N counting, plus a few differences documented in the zsh manual:

  • -q on pushd and popd suppresses the stack printout (and the chpwd hooks).
  • setopt auto_pushd makes every cd push the old directory, so the stack records all moves; pushd_ignore_dups keeps duplicates out and DIRSTACKSIZE=20 caps its length.
  • pushd_minus swaps the meaning of + and -; pushd_to_home makes a bare pushd go to $HOME. Without it, a bare pushd also goes home when the stack has only one entry, where bash reports an error.
  • cd +N and cd -N take that entry out of the stack and change to it, and dirs with arguments replaces the stack with them, with the current directory pushed on top.

Oh My Zsh switches on auto_pushd, pushd_ignore_dups and pushdminus in its lib/directories.zsh, defines the aliases 1 to 9 as cd -1 to cd -9, and adds a d function that runs dirs -v (the first ten entries). That is why typing d, then a number, feels built in there.

pushd and popd on Windows: cmd and PowerShell

cmd.exe has its own pushd and popd with the same idea and fewer features. Microsoft's documentation lists only a path argument: no +N rotation and no dirs. It has one extra trick: with command extensions enabled, pushd \\server\share maps the UNC path to the highest free drive letter, starting at Z:, and popd removes that mapping again. That is handy in batch files that work on a network share:

cmd.exe
pushd \\fileserver\backups
dir
popd

In PowerShell, pushd and popd are aliases for Push-Location and Pop-Location on every platform. Get-Location -Stack lists the stack, and -StackName keeps separate named stacks. They work in any PowerShell drive, so on Windows pushd HKLM:\Software steps into the registry and popd brings you back.

Frequently asked

What is the difference between pushd and cd?

cd changes the directory and remembers only the previous one in $OLDPWD, which cd - returns to. pushd changes the directory and puts the old one on a stack that can hold many entries, so popd, pushd +N or dirs -v can take you back to any of them.

How do I stop pushd from printing the directory stack?

In bash, redirect it: pushd /path > /dev/null. Errors still appear because they go to stderr. In zsh, use pushd -q or set the option pushd_silent.

Why does my script say pushd: not found?

The script runs under sh, which on Debian and Ubuntu is dash, and pushd is not part of POSIX sh. Start the script with #!/bin/bash and run it as ./script.sh or bash script.sh instead of sh script.sh.

Does pushd work in Windows?

Yes. cmd.exe has pushd and popd for a single stack, and pushd with a UNC path maps it to a temporary drive letter when command extensions are enabled. In PowerShell, pushd and popd are aliases for Push-Location and Pop-Location, and Get-Location -Stack shows the stack.

Related articles

All guides