The “n8n: command not found” error means your computer’s command line interface, or shell, cannot locate the n8n executable file it needs to run. This frustrating roadblock typically stems from one of three common issues: a misconfigured system PATH that doesn’t include the location of your n8n installation, a mix-up between a local and global npm installation, or using an outdated Docker command syntax, which is especially common for users migrating from n8n versions below 1.0.
So, Why Can’t My Computer Find n8n?
Let’s be honest, seeing a “command not found” error feels like your computer is just being difficult. But it’s actually a very logical problem. Think of your command line as a workshop, and the n8n command is a specific tool you need, let’s say a special wrench. Your system’s PATH is a list of all the toolboxes it knows to look inside. If your n8n wrench isn’t in any of those registered toolboxes, your shell will throw its hands up and say, “Sorry, can’t find it!”
So, our job isn’t to get mad at the computer; it’s to figure out which toolbox we put the wrench in, or if we forgot to tell the computer about a new toolbox. Let’s diagnose the most common scenarios.
The Top Culprits and How to Fix Them
I’ve seen this issue pop up countless times in the community forums, and it almost always boils down to how you installed n8n. Let’s break it down by the method you used.
Scenario 1: You’re Using Docker (Especially After an Upgrade)
This is the big one, particularly if you’ve recently upgraded from an older n8n version (like 0.2xx) to version 1.0 or newer. A fundamental change was made to how the n8n Docker container starts.
In the past, your command probably looked something like this:
docker run ... n8nio/n8n n8n start --tunnel
Notice that extra n8n before the start command? With n8n v1.0+, the n8n executable became the default entry point for the container. This means you no longer need to explicitly call it. The new, correct command removes it.
The Fix:
Simply remove the redundant n8n from your startup command:
docker run ... n8nio/n8n start --tunnel
Bonus Pro-Tip: While you’re at it, check your volume mount! The path also changed in v1.0.
- Old Path:
-v ~/.n8n:/root/.n8n - New Path:
-v ~/.n8n:/home/node/.n8n
Failing to update this won’t give you a “command not found” error, but it will look like all your workflows and credentials have vanished, which is a different kind of panic!
Scenario 2: You Installed with npm
If you went the Node.js route, the error usually comes from a classic misunderstanding: local vs. global installation.
-
Local Install: If you ran
npm install n8nin a project directory, npm installs n8n’s package files into anode_modulesfolder right there. It does not make then8ncommand available system-wide. Trying to runn8nfrom anywhere else will fail.The Fix: The best way to run a locally installed package is with
npx. Just navigate to your project folder in the terminal and run:
npx n8n startnpxis a fantastic tool included with npm that automatically finds and runs the command from your localnode_modulesdirectory. -
Global Install: If you ran
npm install -g n8n, you were telling npm to install it for all users and projects. This should work out of the box. If it doesn’t, it means we’re dealing with our third scenario.
Scenario 3: Your System’s PATH is Misconfigured
This is the underlying cause for when a global npm install fails. Your shell knows where to find common commands like ls or cd because their locations are listed in the PATH environment variable. When you install a package globally with npm, it places the executable in a specific directory. If that directory isn’t in your PATH, the shell won’t find it.
The Fix:
- Find where npm installs global packages: Run the command
npm config get prefix. This will output a path, for example,/usr/localon macOS or~/.npm-globalon some Linux setups. - Check your PATH: Run
echo $PATH(on macOS/Linux). Look through the output (it’s a colon-separated list) to see if the directory from step 1 (specifically, itsbinsubdirectory, like/usr/local/bin) is present. - Add it to your PATH: If it’s missing, you’ll need to add it by editing your shell’s configuration file (like
~/.zshrc,~/.bashrc, or~/.bash_profile). Add a line like this to the end of the file, replacing the path with the one you found:
export PATH="/usr/local/bin:$PATH"
After saving the file, restart your terminal or run source ~/.zshrc (or the equivalent for your shell) for the changes to take effect.
A Quick Troubleshooting Table
Still not sure? Find your situation in this table for a quick diagnosis.
| How You Installed n8n | Likely Cause | The Quickest Fix |
|---|---|---|
| Docker (Upgraded to v1+) | Outdated docker run command syntax. |
Remove the extra n8n before start. Also, update your volume path to /home/node/.n8n. |
npm install n8n (Local) |
Command is not in the system PATH. | Use npx n8n to run it from the local project folder. |
npm install -g n8n (Global) |
npm’s global bin folder isn’t in your system’s PATH. | Find the folder with npm config get prefix and add its /bin sub-folder to your PATH. |
Execute Command Node |
The command doesn’t exist inside the n8n environment. | Use the command’s absolute path (e.g., /usr/bin/git) or extend your Docker image. |
What About the ‘Execute Command’ Node?
It’s worth mentioning that you might see a similar error—sh: some-command: not found—from inside an n8n workflow using the Execute Command node. This is the same problem in a different context! The n8n execution environment (especially in Docker) is minimal and doesn’t have every tool installed. The solution is to either provide the full, absolute path to the command or, for a more robust fix, create a custom Dockerfile that starts from the n8n image and installs the extra tools you need.
Ultimately, conquering the “n8n: command not found” error is a rite of passage for many self-hosters. By understanding how your shell finds commands, you’re not just fixing a bug—you’re leveling up your entire command-line skillset. Happy automating!
