How to Fix astro: command not found

astro: command not found means your terminal can’t find Astro. Most of the time, you haven’t run npm install yet. Go to your project folder, run npm install, then run npm run dev. That fixes it nine times out of ten.

Why it happens

Astro is not a program on your computer, like a web browser. It lives inside each project, in a folder called node_modules. npm puts it there when you run npm install.

So there are three ways to get this error:

1. You didn’t run npm install. This is common after you download a project, copy a folder, or clone one from GitHub. The node_modules folder isn’t there yet.
2. You’re in the wrong folder. Your terminal is open in a folder with no project in it.
3. You typed astro dev on its own. Your terminal can’t see inside node_modules. It needs npm run dev or npx astro dev to find Astro.

We made a fresh Astro 7.4 project, deleted its node_modules folder, and ran npm run dev. This is what we got:

$ npm run dev
> x@0.0.1 dev
> astro dev
sh: astro: command not found

Typing astro dev on its own gave the same kind of error, even in a project that was installed. In bash it said bash: astro: command not found. On a Mac, the terminal may say zsh: command not found: astro. It’s the same problem.

How to fix it

1. Check your folder. Run ls (or dir on Windows). You should see package.json in the list. If you don’t, use cd to move into your project folder first.
2. Install the tools. Run npm install. It takes a minute. When it’s done, you’ll see a new node_modules folder.
3. Start Astro the right way. Run npm run dev. If you want to type an Astro command yourself, put npx in front, like npx astro dev.

After npm install, we checked that Astro was there:

$ npx astro --version
   astro  v7.4.7

Then npm run dev started the dev server with no errors.

Still stuck?

• Check that Node.js is installed. Run node -v. If you get command not found for node too, install Node.js first.
• If npm install shows red errors, copy the first one and ask an AI to explain it.
• Ask a real person in our community.

Where to go next

• How to fix the most common Astro errors covers the other errors beginners hit.
• Why is my Astro site on port 4322? if your site opens at a strange address.