Installing Gatsby.js on Ubuntu: A Step-by-Step Guide
Installing Gatsby.js on Ubuntu lets you build fast static websites using React. Gatsby.js is a web framework that pulls content from multiple sources to create high-performance web pages.
You need Ubuntu 20.04 or newer and Node.js version 18 or higher to complete the setup. The full process takes about 15 minutes using standard terminal commands. You also need an internet connection and an account that can use sudo. Every command in this guide runs in a terminal, which you can open on most Ubuntu desktops by pressing Ctrl+Alt+T.
Install Node.js via NVM, then install the Gatsby CLI globally using npm. Create a new Gatsby site with `gatsby new` and start the development server with `gatsby develop` in your project directory.
Install NVM (Node Version Manager) and Node.js
Installing NVM (Node Version Manager) on Ubuntu gives you the right environment for your Gatsby.js installation Ubuntu setup by letting you download and manage Node.js properly. You start by updating your package lists and installing curl in your terminal, which allows you to fetch the NVM script safely and set up the core engine your site builder needs.
NVM installs Node.js in your home folder instead of system folders. That means you can install global tools later without sudo, and you can switch Node.js versions whenever a project needs a different one.
Start by updating your system and installing curl. Open a terminal and run the command below. Ubuntu asks for your password, and nothing appears on screen while you type it. That is normal, so type it and press Enter.
sudo apt update sudo apt install curl
Next, download the latest NVM installer. Note: Always verify the script hash provided on the official %📂%LNK0%% NVM repository before running it to ensure security. Piping a script from the internet straight into your shell runs whatever it contains, so it is worth the extra minute to check.
Run the command below. When it finishes, you should see text saying NVM was installed and that it added lines to your shell profile.
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
Refresh your shell so NVM works. Run the command below in the same terminal window. If Ubuntu later says the NVM command is not found, close the terminal, open a new one and try again. A new terminal reads your shell profile from scratch.
source ~/.bashrc
Now, install the current Long Term Support (LTS) version of Node.js, which is v22. Run the command below. NVM downloads Node.js and npm together, and it can take a minute or two depending on your connection. When it finishes, the terminal should report that the new Node.js version is in use.
nvm install 22 nvm use 22
Gatsby CLI
The Gatsby CLI is a tool that helps you create and manage your sites. Install it with the command below. Because NVM keeps Node.js in your home folder, you do not need sudo here. If you see a permissions error, check that you are using the NVM version of Node.js and not one installed through the system package manager.
npm install -g gatsby-cli
Check the version to confirm it is installed. Run the command below. If it prints a version number, the CLI is ready. If the terminal says the command is not found, close it, open a new terminal and run the check again.
gatsby --version
Create Gatsby app
Creating a new Gatsby app on Ubuntu requires the Gatsby command line tool to build your project structure and configuration files automatically. You run the setup command in your terminal, answer a few quick questions about your site name and preferences, and the tool downloads everything you need to start building your web pages.
Move to the folder where you want your project to live before you run the command below. The tool creates a new folder for the project inside whichever folder you are in.
gatsby new
The CLI will ask you a few questions to set up your project. Answer each one and press Enter to move on:
- What would you like to call your site? Choose a name like “myapp”. This is the title of your site.
- What would you like to name the folder? Press Enter to use the default. The default is based on the site name you just gave.
- Will you be using JavaScript or TypeScript? Choose based on your preference. JavaScript is the simpler choice if you are not sure.
- Will you be using a CMS? Select “No” for now. You can connect a content source later.
- Would you like to install a styling system? Choose your preferred CSS framework (like Tailwind or CSS Modules). If you do not need one, you can skip this choice.
The tool will automatically download the necessary files and set up your folder structure. Wait until it returns you to the prompt. This can take several minutes on a slow connection. If you chose the wrong options, delete the new project folder and run the setup again.
Access your app
Accessing your new Gatsby app on Ubuntu involves moving into your project folder and starting the built-in development server. You use the command line to launch the local server, and then you open your web browser to view your live site at the local address while you make changes.
First, change into the project folder with the command below. Use the folder name you picked during setup.
cd myapp/ gatsby develop
Then start the development server with the command below. The first start takes longer than later ones. Leave the terminal open while the server runs. When it is ready, the terminal shows the local address of your site. Open your web browser and go to:
http://localhost:8000
gatsby develop -p 8001. Then open the same address in your browser with the new port number.To stop the server, click the terminal window and press Ctrl+C. Start it again with the same command whenever you want to keep working.
Conclusion
You now have Gatsby.js running on your Ubuntu machine. You have set up the environment, installed the CLI, created a new project, and launched the development server. You are ready to start building your website.
Have a question about this guide?
Answered by AI from this guide. Good questions may be added to this page — please don't include personal details.
Did this guide fix your problem?
About the Author
Richard
Tech Writer, IT Professional
Richard is a writer at Geek Rewind who turns complex IT tasks into clear, step-by-step guides. He draws on years of hands-on experience in system administration and enterprise IT operations, focusing on Windows, Linux and WordPress: the problems people actually run into, and the fixes that work. His server and WordPress guides come from systems he runs himself. Richard builds and maintains the platform behind Geek Rewind, from its Ubuntu servers and Nginx configuration to its custom WordPress plugins. Many new tutorials start with readers' questions, and he's always glad to answer them in the comments.
No comments yet — be the first to share your thoughts!