Installing Gatsby

In a previous post we looked at using a Docker image to manage a Gatsby site. But perhaps you want to install Gatsby directly onto your machine? No problem. Here we’ll look at how to do that on Ubuntu.

I’ll assume that you are starting from a point where the gatsby CLI client is not available on your system.

Terminal window with error message indicating that gatsby command not found.

There are a number of options for how you can install this package.

Account Install

Using npx is the most flexible approach if you do not have root access on your machine.

npx gatsby

It’ll prompt you for permission to install. If you don’t want to be prompted then use the --yes option, in which case the installation will proceed immediately.

npx --yes gatsby
Terminal window showing npx gatsby command.

When the installation is complete you’ll be able to run gatsby with npx.

npx gatsby --version
Terminal window showing npx gatsby --version command.

In this case where is gatsby installed? It’ll get stashed under the .npm hidden directory in your account home directory. With this setup you’ll be able to run gatsby from anywhere on your system, provided that you run it through npx.

Terminal window showing location of Gatsby when installed in an account.

Project Install

You can install gatsby within a specific project. Create a directory for the project (or use an existing project directory). Then run npm install from within that directory.

npm install gatsby-cli

That will install gatsby under the node_modules directory within the project directory.

Terminal window showing location of Gatsby when installed in a project.

Now, unfortunately, the gatsby executable will be installed into a directory which does not lie on your execution path. This means that simply running gatsby won’t work because your shell won’t know where to find the executable.

However, once again, you can use npx, which will find the executable by looking under node_modules.

npx gatsby --version

However, if you move to another directory then npx will no longer be able to find the gatsby executable and will prompt you to install again.

You might strongly dislike having to precede the command with npx. There is another option!

Global Install

You can use the -g option of npm install to install gatsby globally. Since you’ll be installing this system-wide you’ll need to precede the command with sudo to get elevated privileges.

sudo npm install -g gatsby-cli

The gatsby executable will be installed into /usr/local/bin/, which should be part of all users’ execution paths.

Terminal window showing location of Gatsby when installed globally.

This will mean that:

  • you can run gatsby from anywhere without using npx and
  • any other users on the system will also be able to run gatsby.

Remove Gatsby

Despite spending all of that effort to install Gatsby, at some stage you might find that you want to remove it from your system. No problem.

If you installed via npx then you’ll need to track down the relevant files under the ~/.npm directory and delete them. The location of these files will vary from machine to machine, but you can use the find command from the screenshot above to locate them.

If you installed into a project then there are two approaches:

# Remove the gatsby-cli package.
npm uninstall gatsby-cli
# A rather aggressive approach: remove all packages.
rm -rf node_modules/

If you installed globally then you can use npn uninstall with the -g option.

sudo npm uninstall -g gatsby-cli


Q. I get a command not found error.
A. This means that your shell can’t find gatsby in your executable path. The easiest way to fix this is a global install.


We’re looked at a few options for installing the Gatsby CLI. There are likely other approaches but these are the ones that I have used most frequently.