> ## Content Index
> Fetch the complete content index at: https://linuxhandbook.com/llms.txt
> Use this file to discover other available public pages before exploring further.

# CDPATH: The Forgotten Magic Trick in Your Bash Toolbox
- URL: https://linuxhandbook.com/cdpath/
- Published: 2025-04-25T15:25:16.000Z
- Updated: 2025-04-25T15:25:16.000Z
- Description: A tiny little mechanism that will save you from typing those long paths for the frequently visited directories.
- Author: Abhishek Prakash
- Tags: Tips

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](https://linuxhandbook.com/deploy-ghost-docker/) 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](https://linuxhandbook.com/add-to-path/) (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 `cd`s 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?

🚧

You should always add `.` (current directory) in the CDPATH and your CDPATH should start with it. This way, it will look for the directory in the current directory first and then in the directories you have specified in the CDPATH variable.

## 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 

🚧

The order of the directories in CDPATH matters.

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.

💡

If things look fine in your testing, you should make it permanent by adding the "export CDPATH" command you used earlier to your shell profile.

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. 

📋

When you use cd command with absolute path or relative path, it won't refer to the CDPATH. CDPATH is more like, hey, instead of just looking into my current sub-directories, search it in specified directories, too. When you specify the full path (absolute or relative) already with cd, there is no need to search. cd knows where you want to go.

## How to find the CDPATH value?

CDPATH is an environment variable. How do you [print the value of an environment variable](https://linuxhandbook.com/print-environment-variables/)? Simplest way is to [use the echo command](https://linuxhandbook.com/echo-command/):

```
echo $CDPATH
```

📋

If you have tab completion set with cd command already, it will also work for the directories listed in 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.

💡

Including `..` (parent directory) in your `CDPATH` creates a super-neat effect: you can navigate to 'sibling directories' without typing `../`. If you're in `/usr/bin` and want to go to `/usr/lib`, just type `cd lib`.

## **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](https://github.com/wting/autojump?ref=linuxhandbook.com) instead of CDPATH.

[GitHub - wting/autojump: A cd command that learns - easily navigate directories from the command lineA cd command that learns - easily navigate directories from the command line - wting/autojump![](https://linuxhandbook.com/content/images/icon/pinned-octocat-093da3e6fa40-20.svg)GitHubwting![](https://linuxhandbook.com/content/images/thumbnail/autojump)](https://github.com/wting/autojump?ref=linuxhandbook.com)

*🗨️ 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?*