CDPATH: The Forgotten Magic Trick in Your Bash Toolbox

If you manage servers on a regular basis, you'll often find yourself entering some directories more often than others.

For example, I self-host Ghost CMS to run this website. The Ghost install is located at /var/www/ghost/ . I have to cd to this directory and then use its subdirectories to manage the Ghost install. If I have to enter its log directory directly, I have to type /var/www/ghost/content/log.

Typing out ridiculously long paths that take several seconds even with tab completion.

Relatable? But what if I told you there's a magical shortcut that can make those lengthy directory paths vanish like free merchandise at a tech conference?

Enter CDPATH, the unsung hero of Linux navigation that I'm genuinely surprised that many new Linux users are not even aware of!

What is CDPATH?

CDPATH is an environment variable that works a lot like the more familiar PATH variable (which helps your shell find executable programs). But instead of finding programs, CDPATH helps the cd command find directories

Normally, when you use cd some-dir, the shell looks for some-dir only in the current working directory.

With CDPATH, you tell the shell to also look in other directories you define. If it finds the target directory there, it cds into it — no need to type full paths.

How does CDPATH works?

Imagine this directory structure:

/home/abhishek/
├── Work/
│   └── Projects/
│       └── WebApp/
├── Notes/
└── Scripts/

Let's say, I often visit the WebApp directory and for that I'll have to type the absolute path if I am at a strange location:

cd /home/abhishek/Work/Projects/WebApp

Or, since I am a bit smart, I'll use ~ shortcut for home directory.

cd ~/Work/Projects/WebApp

But if I add this location to the CDPATH variable:

export CDPATH=$HOME/Work/Projects

I could enter WebApp directory from anywhere in the filesystem just by typing this:

cd WebApp

Awesome! Isn't it?

How to set CDPATH variable?

Setting up CDPATH is delightfully straightforward. If you ever added anything to the PATH variable, it's pretty much the same.

First, think about the frequently used directories where you would want to cd to search for when no specific paths have been provided.

Let's say, I want to add /home/abhishek/work and /home/abhishek/projects in CDPATH. I would use:

export CDPATH=.:/home/abhishek/work:/home/abhishek/projects

This creates a search path that includes:

1. The current directory (.)
2. My work directory
3. My projects directory

Which means if I type cd some_dir, it will first look if some_dir exists in the current directory. If not found, it searches

Let's say that both work and projects directories have a directory named docs which is not in the current directory.

If I use cd docs, it will take me to /home/abhishek/work/docs. Why? because work directory comes first in the CDPATH.

Whatever you exported in CDPATH will only be valid for the current session. To make the changes permanent, you should add it to your shell profile.

I am assuming that you are using bash shell. In that case, it should be _/.profile~ or ~/.bash_profile.

Open this file with a text editor like Nano and add the CDPATH export command to the end.

How to find the CDPATH value?

CDPATH is an environment variable. How do you print the value of an environment variable? Simplest way is to use the echo command:

echo $CDPATH

When not to use CDPATH?

Like all powerful tools, CDPATH comes with some caveats:

1. Duplicate names: If you have identically named directories across your filesystem, you might not always land where you expect.
2. Scripts: Be cautious about using CDPATH in scripts, as it might cause unexpected behavior. Scripts generally should use absolute paths for clarity.
3. Demo and teaching: When working with others who aren't familiar with your CDPATH setup, your lightning-fast navigation might look like actual wizardry (which is kind of cool to be honest) but it could confuse your students.

Why aren’t more sysadmins using CDPATH in 2025?

The CDPATH used to be a popular tool in the 90s, I think. Ask any sysadmin older than 50 years, and CDPATH would have been in their arsenal of CLI tools.

But these days, many Linux users have not even heard of the CDPATH concept. Surprising, I know.

Ever since I discovered CDPATH, I have been using it extensively specially on the Ghost and Discourse servers I run. Saves me a few keystrokes and I am proud of those savings.

By the way, if you don't mind including 'non-standard' tools in your workflow, you may also explore autojump instead of CDPATH.

GitHub - wting/autojump: A cd command that learns - easily navigate directories from the command line

A cd command that learns - easily navigate directories from the command line - wting/autojump

GitHubwting

🗨️ Your turn. Were you already familiar with CDPATH? If yes, how do you use it? If not, is this something you are going to use in your workflow?