Fixing 'Command Not Found' Right After Installing Something

“Command not found” immediately after installing something that definitely exists on disk is, in the overwhelming majority of cases, a $PATH problem — the shell searches a specific, ordered list of directories for commands, and the tool you installed isn’t in any of them yet.

Step 1: confirm the binary actually exists and where

find / -name "toolname" -type f 2>/dev/null

Confirming the installed binary’s actual location is the necessary first step — if the file genuinely isn’t there at all, this is an installation problem, not a $PATH problem, and no shell configuration fix will help.

Step 2: check your current PATH

echo $PATH

$PATH is a colon-separated list of directories the shell searches, in order, when you type a command name — if the directory containing your newly installed tool isn’t in this list, the shell will never find it regardless of how certain you are that the file exists.

Step 3: add the missing directory to PATH

# Bash: in ~/.bashrc
export PATH="$HOME/.local/bin:$PATH"

# Zsh: in ~/.zshrc
export PATH="$HOME/.local/bin:$PATH"

Add the specific directory containing your tool, then reload your shell configuration (source ~/.bashrc or open a new terminal) for the change to take effect in existing sessions.

Step 4: check for a shell hash cache holding a stale “not found” result

hash -r

Bash (and other shells) cache the resolved location of commands you’ve run for performance — if you install a tool with the exact same name as something the shell previously failed to find, that stale “not found” cache entry can persist; hash -r clears it and forces a fresh $PATH search.

Step 5: check whether you edited the right shell’s config file

echo $SHELL

A very common specific mistake: editing .bashrc while your actual default shell is Zsh (which reads .zshrc instead), or vice versa — confirm which shell you’re actually running before assuming a config edit should have taken effect.

# .bash_profile / .profile: read by LOGIN shells
# .bashrc: read by INTERACTIVE non-login shells

Depending on how a specific terminal or session is launched, only one of these file types may actually get sourced — a $PATH addition placed in the wrong one can appear to “not work” despite being correctly written, simply because that specific file isn’t read in that specific context.

Step 7: verify the fix took effect

which toolname
toolname --version

Confirming which now resolves the command, and that actually running it works, verifies the fix rather than just assuming the configuration change was sufficient.

Step 8: check for an installation method that uses a non-standard directory

Some installation methods (certain language-specific package managers, tools installed via a script rather than a system package manager) place binaries in less conventional locations — checking the specific installer’s own documentation for exactly where it places files avoids guessing at directories that might not actually be where the tool landed.

Why understanding PATH as an ordered search list, not shell magic, resolves this quickly

Once you internalize that “command not found” specifically means “not present in any directory currently listed in $PATH,” the fix becomes mechanical: find where the binary actually is, confirm that directory is in $PATH, and confirm the shell configuration adding it is actually being read in your specific session type.

When “command not found” is genuinely a missing package, not a PATH problem

On Ubuntu and Debian-derived distributions, Bash’s command_not_found_handle hook (backing the command-not-found package) intercepts an unresolved command and searches the package database for something that would actually provide it, printing a specific installation suggestion rather than a bare error — genuinely different from every scenario covered above, since here the binary doesn’t exist on disk at all yet. If the suggested install command looks stale or wrong, sudo apt update && sudo update-command-not-found refreshes the underlying lookup database before you assume the suggestion itself is broken.

Step 9: on macOS specifically, check /etc/paths and /etc/paths.d

cat /etc/paths
ls /etc/paths.d/

macOS constructs part of the system-wide $PATH from /etc/paths plus every file inside /etc/paths.d/, each contributing one additional directory, independently of anything in .zshrc or .bash_profile — a mechanism most Linux distributions don’t have at all. Some macOS installers (certain developer toolchains and language runtimes in particular) write directly into /etc/paths.d/ rather than touching your shell’s own dotfiles, which is worth checking specifically if a tool installed via a .pkg installer still isn’t found even after confirming your shell config files look correct.

Related:

Sources:

Suggest Package Installation When Command Not Found — OSTechNix