Header Ads

Ionic is not recognized

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 Linux
bash: ionic: command not found
zsh: command not found: ionic

# Windows PowerShell
ionic : File C:\Users\you\AppData\Roaming\npm\ionic.ps1 cannot be loaded because
running 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 -v
npm -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/cli
ionic --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 ionic
npm 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 ~/.zshrc
hash -r
ionic --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 18
npm install -g @ionic/cli
ionic --version # works

nvm use 20
ionic --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-global
npm config set prefix ~/.npm-global
export 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/cli
npm cache verify
npm 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 seeLikely causeFix
ionic is not recognized right after installTerminal opened before install, or npm folder not on PATHSteps 2 and 3
npx @ionic/cli works, ionic does notPATH problemStep 3
Worked yesterday, gone today, you use nvmSwitched Node versionStep 4
ionic.ps1 cannot be loadedPowerShell script policyStep 5
EACCES during installGlobal folder owned by rootStep 6
Installed ionic package long agoOld package nameStep 2


Debug Checklist

  1. Run node -v and npm -v. Both must work.
  2. Run npm install -g @ionic/cli and read the end of the output for errors.
  3. Close the terminal, open a new one, and run ionic --version.
  4. Run npm prefix -g and check that its folder (or its bin folder) is on your PATH.
  5. If you use nvm, check node -v and reinstall the CLI under the active version.
  6. 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.

Related Guides

Post a Comment

0 Comments