When the shell can't find your new tool
You run cargo install ripgrep. The terminal scrolls through compilation steps, ends with Installed package ripgrep v1.13.0, and returns to the prompt. You type rg --help. The shell replies command not found: rg. You just installed it. The compiler built it. The binary exists somewhere on your disk. Your shell simply refuses to acknowledge it.
This happens because cargo install places executables in a directory that your shell does not check by default. The binary is safe and sound, but your shell is looking in the wrong rooms. Fixing this requires adding the Cargo bin directory to your shell's search path.
The PATH variable controls what the shell can see
Your shell finds commands using an environment variable called PATH. This variable holds a list of directories separated by a delimiter. When you type a command, the shell iterates through that list, checks each folder for a file with the matching name, and runs the first match it finds. If the shell reaches the end of the list without a match, it reports command not found.
cargo install puts new binaries in ~/.cargo/bin. On Windows, this resolves to %USERPROFILE%\.cargo\bin. If ~/.cargo/bin is not in your PATH, the shell never inspects that folder. The binary is invisible to the shell, even though it is right there.
The fix is to append ~/.cargo/bin to your PATH. This tells the shell to include the Cargo bin directory in its search routine.
Minimal fix: add the bin directory
Run this command to update PATH for the current session. This change vanishes when you close the terminal.
// This updates PATH for the current shell session only.
// The change does not persist across restarts.
export PATH="$HOME/.cargo/bin:$PATH"
Verify the fix by running your installed tool.
// The shell should now find the binary.
// If you still see "command not found", check the binary name.
// Some crates install binaries with names different from the crate name.
rg --help
To make the change permanent, add the export line to your shell configuration file. The file name depends on your shell.
How cargo install actually works
cargo install performs three steps. First, it fetches the crate source from crates.io or a local path. Second, it compiles the crate in release mode. Third, it copies the resulting binary to ~/.cargo/bin.
Cargo does not modify your shell configuration. It assumes you manage your own environment. This is a design choice. Cargo keeps your dotfiles clean and avoids conflicts with other package managers. The responsibility for PATH lives with the shell, not the build tool.
This separation means rustup and cargo can be reinstalled or moved without breaking your shell setup, provided you update PATH correctly. It also means you can point PATH to a custom directory if you prefer to store binaries elsewhere.
Realistic setup for your shell
Add the export line to your shell's startup file. This ensures PATH includes the Cargo bin directory every time you open a terminal.
Bash and Zsh
Bash reads ~/.bashrc for interactive non-login shells. Zsh reads ~/.zshrc. Add the export to the appropriate file.
# Append the Cargo bin directory to PATH.
# Use $HOME instead of ~ to ensure correct expansion in all contexts.
export PATH="$HOME/.cargo/bin:$PATH"
Reload the configuration to apply changes immediately.
# Source the config file to update the current session.
# This avoids closing and reopening the terminal.
source ~/.bashrc
Fish
Fish uses ~/.config/fish/config.fish. Fish handles paths slightly differently. Use fish_add_path for the cleanest result.
# Add the Cargo bin directory to PATH.
# fish_add_path prevents duplicates and handles separators automatically.
fish_add_path $HOME/.cargo/bin
Windows PowerShell
PowerShell uses a profile script. The path separator on Windows is a semicolon, not a colon.
# Append the Cargo bin directory to the user PATH.
# This updates the environment variable for the current session.
$env:Path += ";$env:USERPROFILE\.cargo\bin"
# Persist the change to the user environment variable.
# This ensures the path survives terminal restarts.
[System.Environment]::SetEnvironmentVariable("Path", $env:Path, "User")
Restart PowerShell for the persistent change to take effect.
Convention aside: use the cargo env script
The Rust installer creates a helper script at ~/.cargo/env. This script exports PATH and other variables. Sourcing this script is the community convention for setting up the environment.
# Source the cargo env script in your shell config.
# This is safer than hardcoding the path because rustup manages the script.
# If rustup changes the directory structure, the script updates automatically.
source "$HOME/.cargo/env"
Add source "$HOME/.cargo/env" to your ~/.bashrc or ~/.zshrc. This approach delegates path management to rustup. It reduces the chance of configuration drift.
Pitfalls and debugging
Binary name mismatch
The crate name and the binary name are not always the same. cargo install ripgrep installs a binary named rg. cargo install fd-find installs fd. If you guess the wrong name, the shell reports command not found.
Check the installed binary name with cargo install --list.
// List all binaries installed via cargo install.
// The output shows the package name and the binary name.
cargo install --list
Windows path separators
Windows uses semicolons to separate paths. Linux and macOS use colons. If you copy a Linux command to Windows, the shell may treat the colon as part of the path, breaking the list. Always use the correct separator for your OS.
Subshells and SSH
Some terminal emulators start login shells that source ~/.profile instead of ~/.bashrc. If you put the export in ~/.bashrc, the path might not load. SSH sessions often behave this way. Put the export in ~/.profile or ensure ~/.profile sources ~/.bashrc.
Debugging with which and type
Use which or type to see where the shell finds a command. If the command is missing, these tools confirm the shell cannot locate it.
# Show the full path to the binary the shell will run.
# If this returns nothing, the binary is not in PATH.
which rg
# Show how the shell interprets the command.
# This reveals aliases and functions that might shadow the binary.
type rg
Check your PATH directly to verify the Cargo bin directory is present.
# Print the current PATH variable.
# Look for ~/.cargo/bin in the output.
echo $PATH
Trust the output. If ~/.cargo/bin is missing from PATH, the shell will never find your binaries.
Decision: cargo install vs system packages vs cargo run
Choose the installation method based on your update cadence and workflow.
Use cargo install when you need the latest version of a tool that your system package manager has not updated yet. Use cargo install when you want to test a tool without affecting your system's global state. Use cargo install when you are working on a project that requires a specific tool version not available in your OS repositories.
Use your system package manager (apt, brew, pacman, winget) when you want automatic updates integrated with your OS. Use system packages when you prefer dependency tracking managed by your distribution. Use system packages when you need the tool to be available to all users on the machine.
Use cargo run --bin name when you are developing a tool and need to test changes without reinstalling. Use cargo run when you want to execute a binary from a local source directory without copying it to ~/.cargo/bin.
Use cargo install --path . when you want to install a local crate as a global binary for testing. Use this flag when you are iterating on a tool and want to simulate the installed experience.
Pick the tool that matches your update cadence. System packages for stability, Cargo for bleeding edge.