how to solve command not found when using rustup

Nov 16, 2025

1. The purpose of this post

Have you ever installed a new tool, watched the installation script finish successfully, and then immediately hit a dreaded ‘command not found‘ error when you tried to run it? It’s a frustrating, yet incredibly common, experience.

This article addresses that exact scenario with the Rust programming language and its official toolchain installer, rustup. We’ll look at why, even after running the successful one-line installation script, your shell can’t find rustup or cargo (Rust’s build system and package manager). The goal is to demystify the shell environment and provide a clean, permanent solution so you can get back to writing fast, safe code.

2. understanding the problem

💡 Environment Context: The Shell and the PATH

When you execute a command like cargo –version in your terminal (which, in our example, is zsh), the shell searches through a list of directories defined by an environment variable called PATH.

For zsh or bash to find an executable (like cargo), the directory containing that executable must be explicitly listed in the PATH.

🧑‍💻 The Problematic Scenario

You run the official installation command:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

The script runs, downloads the toolchain, and tells you it installed everything into the ** /.cargo/bin** directory. However, when you try to use the tools:

➜  ~ rustup update
zsh: command not found: rustup
➜  ~

➜  ~ cargo --version
zsh: command not found: cargo
➜  ~

💥 Deep Analysis: Source vs. Execute

The core issue here lies in shell session scope.

The Installation Script’s Action: The rustup installer is smart. It not only puts the binaries into ~/.cargo/bin but also creates a crucial script, typically at ~/.cargo/env . This script contains the necessary logic to add ~/.cargo/bin to your current PATH.

The Shell’s Blind Spot: The installation script runs in its own sub-shell environment. While it successfully modifies the PATH in its sub-shell, that change does not propagate back to your main, running terminal session. The moment the installation script finishes, its temporary environment is destroyed, and your terminal’s PATH remains unchanged.

Simply put, the changes that make ‘rustup‘ accessible are only active after the installation, but you haven’t yet told your current shell session to load those changes.

3. The solution

🚀 Immediate Fix: Sourcing the Environment

The temporary (but essential!) solution is to manually tell your current shell to execute the environment script that rustup created. This is done using the ‘source‘ command (or its shorter alias, ‘.‘).

~ source ~/.cargo/env

After running this, the PATH is updated in your current session:

➜  ~ source ~/.cargo/env
➜  ~ rustup
rustup 1.28.2 (e4f3ad6f8 2025-04-28)
The Rust toolchain installer
# ... success!

permanence: The .zshrc or .bashrc Solution

A temporary fix is great for testing, but nobody wants to type ‘source /.cargo/env‘ every time they open a new terminal.

To make the change permanent, you need to add the ‘source‘ command to your shell’s startup file.

If you are using zsh (common on modern macOS and some Linux distributions), edit /.zshrc :

# Add this to your ~/.zshrc file
# rust
source ~/.cargo/env

If you are using bash (common on Linux), edit /.bashrc or /.profile :

# Add this to your ~/.bashrc or ~/.profile file
# rust
source ~/.cargo/env

After adding the line, save the file and open a new terminal window (or run source ~/.zshrc to reload the current one). You’ll find your Rust tools are now instantly available!

4. Why it works

When you use the source command, you are telling the shell to execute the script in the current shell context, rather than launching a new sub-shell to execute it.

The ~/.cargo/env script essentially contains a command like this:

export PATH="$HOME/.cargo/bin:$PATH"

By sourcing it:

The shell reads this line.

It uses the export command to modify the PATH variable for the current running session.

Any subsequent command you type (like cargo) will use this newly updated PATH to find the executable in ~/.cargo/bin .

By placing this source command in your shell startup file (.zshrc, .bashrc, etc.), you guarantee that this PATH modification happens automatically every single time you launch a new terminal, solving the problem forever.

5. Summary

🎯 Root Cause Summary

The ‘command not found‘ error after installing rustup is not a failure of the installation, but a scoping issue with the shell environment. The installer updates the PATH variable, but only within its own, temporary sub-shell. Your main terminal session needs to be explicitly told to load the PATH update from the ~/.cargo/env script.

Happy coding! Now that your environment is properly configured, you can start exploring the powerful features of Rust. Welcome to the world of performance and safety!

Final Words + More Resources

My intention with this article was to help others share my knowledge and experience. If you want to contact me, you can contact by email: Email me

Here are also the most important links from this article along with some further resources that will help you in this scope:

👨‍💻 rust

Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!