Getting “ionic is not recognized as an internal or external command”, “ionic: command not found” or a PowerShell error when you run the Ionic CLI? This guide shows how to find the cause and fix it in 6 steps on Windows, macOS and Linux, including the nvm and PATH problems that surprise most developers.
You install Ionic, open a terminal, and type your first command. Instead of starting a project, you see one of these:
# Windows Command Prompt'ionic' is not recognized as an internal or external command,operable program or batch file.
# macOS or Linuxbash: ionic: command not foundzsh: command not found: ionic
# Windows PowerShellionic : File C:\Users\you\AppData\Roaming\npm\ionic.ps1 cannot be loaded becauserunning scripts is disabled on this system.
All of these mean the same thing at first: your terminal cannot find a program called ionic. The reasons are different, and the steps below go from the most common to the least common.
Step 1: Check Node.js and npm First
The Ionic CLI is installed with npm, so Node.js must work before anything else:
node -vnpm -v
If either command fails, install the current LTS version of Node.js from the official website, close the terminal and open a new one. If both work, move on.
Step 2: Install the Ionic CLI the Right Way
The CLI lives in the package @ionic/cli. Install it globally, then check the version:
npm install -g @ionic/cliionic --version
Many old tutorials tell you to run npm install -g ionic. That is the old package name. If you installed it before, remove it first so the two do not conflict:
npm uninstall -g ionicnpm install -g @ionic/cli
If you do not want to install anything globally, you can run the CLI on demand with npx. This is also a quick way to test whether your problem is a PATH problem:
npx @ionic/cli start myApp tabs
If npx works but ionic does not, the CLI is fine and your terminal cannot see npm’s global folder. Go to Step 3.
Step 3: Fix the PATH (Where Your Terminal Looks for Programs)
A global npm package puts a small launcher file in npm’s global folder. Your terminal finds it only if that folder is on the PATH. First, find the folder:
npm prefix -g
On Windows this is usually C:\Users\YourName\AppData\Roaming\npm. On macOS and Linux, the launchers are in the bin folder inside that path, for example /usr/local/bin or ~/.npm-global/bin.
Windows: open the Start menu, search for Edit the system environment variables, open Environment Variables, select Path under your user variables, and add the npm folder. Close and reopen the terminal afterwards, because old windows do not see the change.
macOS and Linux: add the folder to your shell profile. For zsh, edit ~/.zshrc (for bash, ~/.bashrc):
export PATH="$(npm prefix -g)/bin:$PATH"
Then reload the file and clear the shell’s memory of commands:
source ~/.zshrchash -rionic --version
Step 4: If You Use nvm, Install the CLI for Each Node Version
This is the hidden cause that surprises many developers. Version managers such as nvm keep a separate set of global packages for every Node.js version. If you install the Ionic CLI while using Node 18 and later switch to Node 20, the ionic command disappears:
nvm use 18npm install -g @ionic/cliionic --version # works
nvm use 20ionic --version # command not found: installed under Node 18 only
The fix is to install the CLI again after you switch, or to use npx @ionic/cli for one-off commands. Check which Node version you are using with node -v whenever the command is missing.
Step 5: Fix the PowerShell “Running Scripts Is Disabled” Error
On Windows PowerShell, the launcher is a script file, and the default policy can block scripts. The error mentions ionic.ps1 cannot be loaded because running scripts is disabled. You have two choices:
- Use Command Prompt or Git Bash instead of PowerShell. They do not have this restriction, and this is the simplest option.
- Allow locally created scripts for your user. This changes a security setting, so read what it does before you run it:
Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned
RemoteSigned lets scripts you wrote or installed locally run, and requires a signature for scripts downloaded from the internet. If you work on a company computer, your administrator may control this setting, so ask before you change it.
Step 6: Fix Permission Errors and Broken Installs
If the install itself fails with EACCES: permission denied on macOS or Linux, do not fix it with sudo npm install -g. That leaves files owned by the wrong user and causes more problems later. Better options:
- Install Node.js with
nvm, which keeps everything inside your home folder. This also avoids the permission error completely. - Or tell npm to use a global folder in your home directory, and add that folder to your PATH as in Step 3.
mkdir -p ~/.npm-globalnpm config set prefix ~/.npm-globalexport PATH="$HOME/.npm-global/bin:$PATH"
If the command exists but crashes with a Cannot find module error, the installation is corrupted. Remove it and install it again:
npm uninstall -g @ionic/clinpm cache verifynpm install -g @ionic/cli
My guide on fixing the “Cannot find module” error in Node.js explains this kind of error in more detail.
Quick Diagnosis Table
| What you see | Likely cause | Fix |
|---|---|---|
ionic is not recognized right after install | Terminal opened before install, or npm folder not on PATH | Steps 2 and 3 |
npx @ionic/cli works, ionic does not | PATH problem | Step 3 |
| Worked yesterday, gone today, you use nvm | Switched Node version | Step 4 |
ionic.ps1 cannot be loaded | PowerShell script policy | Step 5 |
EACCES during install | Global folder owned by root | Step 6 |
Installed ionic package long ago | Old package name | Step 2 |
Debug Checklist
- Run
node -vandnpm -v. Both must work. - Run
npm install -g @ionic/cliand read the end of the output for errors. - Close the terminal, open a new one, and run
ionic --version. - Run
npm prefix -gand check that its folder (or itsbinfolder) is on your PATH. - If you use nvm, check
node -vand reinstall the CLI under the active version. - On Windows PowerShell, try Command Prompt to rule out the script policy.
Conclusion
“ionic is not recognized” almost never means the Ionic CLI is broken. Your terminal simply cannot find it. Install @ionic/cli with npm, make sure npm’s global folder is on your PATH, reinstall after switching Node versions with nvm, and use Command Prompt if PowerShell blocks scripts. When in doubt, npx @ionic/cli gets you working while you fix the setup.

0 Comments