How To Install Astro on Ubuntu 24.04 LTS

If you build content-heavy websites — blogs, documentation portals, marketing pages — you already know the frustration of bloated JavaScript frameworks slowing your site to a crawl. Astro solves that problem by shipping zero JavaScript to the browser by default, letting you build blazing-fast websites with the tools you already know.

This guide walks you through exactly how to install Astro on Ubuntu 24.04 LTS from scratch. Whether you are running a local development machine or a remote VPS, every step is covered — from updating your system to launching your first Astro dev server.

By the end, you will have a fully working Astro project running on Ubuntu 24.04, a solid understanding of the project structure, and the know-how to troubleshoot the most common installation errors. This guide is written and tested by a sysadmin who works daily with Linux servers, so everything here reflects real-world practice.

What Is Astro and Why Should You Use It?

Astro is a modern, content-first web framework designed to generate fast static websites. Unlike Next.js or Nuxt, Astro uses an Islands Architecture, which means only the interactive parts of your page ship JavaScript — the rest renders as pure, lightweight HTML.

That distinction matters enormously for performance. A typical React site ships hundreds of kilobytes of JavaScript before rendering a single line of text. An equivalent Astro site often ships near zero.

As of early 2026, Astro is backed by Cloudflare after the two companies partnered in January 2026, signaling serious enterprise confidence in the framework. Astro 5.x is currently the stable release, with Astro 6.0 beta introducing a workerd-based dev server, native Content Security Policy (CSP) support, and live content collections.

Key Reasons Developers Choose Astro

• Zero JavaScript by default — faster page load and better Core Web Vitals
• Framework-agnostic — use React, Vue, Svelte, or Solid components inside Astro
• Built-in Markdown/MDX support — ideal for blogs and documentation
• File-based routing — no complex router configuration needed
• SEO-optimized out of the box — static HTML output is easily crawlable
• Cloudflare-backed future — long-term stability and edge deployment support

Prerequisites for Astro on Ubuntu 24.04 Setup

Before you begin the Astro on Ubuntu 24.04 setup, confirm that you have the following in place. Skipping this section is the single most common cause of failed installations.

System Requirements

• Ubuntu 24.04 LTS (Noble Numbat) — fresh install or upgraded system
• A user account with sudo privileges
• Stable internet connection
• At least 1 GB of free disk space (2 GB recommended)

Required Tools

• Node.js — v18.20.8, v20.3.0, or v22.0.0 or higher (v19 and v21 are NOT supported by Astro)
• npm — comes bundled with Node.js (v7+ recommended)
• A terminal — Ubuntu’s built-in GNOME Terminal, or SSH for remote servers
• A text editor — VS Code with the official Astro extension is strongly recommended

Recommended knowledge level: You should be comfortable running basic Linux commands like cd, ls, sudo apt, and reading terminal output.

Step 1: Update Your Ubuntu 24.04 System

Every solid Linux server tutorial starts here. Updating your system before installing anything ensures you get the latest package metadata, security patches, and compatible dependency versions.

Run the following command:

sudo apt update && sudo apt upgrade -y

Here is what each part does:

• sudo apt update — refreshes the local package index from Ubuntu’s repositories
• sudo apt upgrade -y — upgrades all installed packages to their latest versions; -y auto-confirms every prompt

Expected output (partial):

Reading package lists... Done
Building dependency tree... Done
...
0 upgraded, 0 newly installed, 0 to remove and 0 not upgraded.

If the upgrade installs a new kernel, reboot your machine before continuing:

sudo reboot

Pro Tip: If you are working on a cloud VM (DigitalOcean, Linode, AWS), take a snapshot of your instance now. It takes 30 seconds and saves hours if something goes wrong later.

Install Essential Build Tools

Some Node.js packages compile native extensions. Install build-essential and curl now to avoid dependency errors later:

sudo apt install -y curl build-essential

Step 2: Install Node.js on Ubuntu 24.04 LTS Using NVM

Astro’s entire CLI runs on Node.js. This is the most important prerequisite step, and the method you choose here will affect your entire development workflow.

Why NVM Is the Right Choice

You have three main options for installing Node.js on Ubuntu 24.04:

NVM is the recommended method for developers. It lets you install multiple Node.js versions side by side and switch between them instantly — critical when different projects require different Node versions.

Installing NVM on Ubuntu 24.04

Step 2a: Download and run the official NVM install script:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

This script clones the NVM repository into ~/.nvm and adds the necessary lines to your ~/.bashrc file.

Step 2b: Load NVM into your current shell session without restarting it:

export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"

Step 2c: Verify NVM installed correctly:

nvm --version

Expected output:

0.39.7

Installing a Compatible Node.js Version

Astro requires Node.js v18.20.8, v20.3.0, or v22.0.0 or higher. Odd-numbered versions (v19, v21) are explicitly not supported. For the most stable experience in 2026, install Node.js v20 LTS:

nvm install 20
nvm use 20

Set it as your default so every new terminal session uses it automatically:

nvm alias default 20

Step 2d: Confirm both Node.js and npm are installed and working:

node -v
npm -v

Expected output:

v20.19.0
10.9.2

If you see version numbers, you are ready to move forward.

Step 3: Install Astro on Ubuntu 24.04 LTS

Now for the main event. This section covers both the automatic CLI wizard (recommended for most users) and the manual method for advanced users who want full control.

Method 1: Automatic Installation via the CLI Wizard (Recommended)

The create astro CLI command is the official, fastest way to scaffold a new Astro project. It handles directory creation, dependency installation, TypeScript setup, and git initialization — all through an interactive prompt.

Run this command from any directory:

npm create astro@latest

Walkthrough of the CLI Prompts

The CLI launches an interactive wizard. Here is what each prompt asks:

Prompt 1: Where should we create your new project?

./my-astro-project

Prompt 2: How would you like to start your new project?

❯ A basic, minimal starter (recommended)
  Use blog template
  Use docs (Starlight) template
  Use a community theme

Select “A basic, minimal starter” for this tutorial.

Prompt 3: Install dependencies? → Select Yes

Prompt 4: Initialize a new git repository? → Select Yes (recommended)

Once the wizard completes, you will see:

 launch  Houston:
         Good luck out there, astronaut! 🚀

That’s Astro’s mascot confirming a successful install.

Method 2: Manual Installation (Advanced Users)

If you prefer full control over your project setup, install Astro manually.

Step a: Create and enter your project directory:

mkdir my-astro-project && cd my-astro-project

Step b: Initialize a package.json:

npm init -y

Step c: Install Astro as a dependency:

npm install astro

Step d: Open package.json and replace the "scripts" section with:

"scripts": {
  "dev": "astro dev",
  "build": "astro build",
  "preview": "astro preview"
}

Step e: Create the required directory structure and your first page:

mkdir -p src/pages
echo '<html><body><h1>Hello, Astro!</h1></body></html>' > src/pages/index.astro

Step f: Create the Astro configuration file:

touch astro.config.mjs

Add the following content to astro.config.mjs:

import { defineConfig } from 'astro/config';

export default defineConfig({});

Step 4: Start the Astro Development Server

Navigate into your project directory if you are not already there:

cd my-astro-project

Start the development server:

npm run dev

Expected terminal output:

 astro  v5.x.x ready in 312 ms

┃ Local    http://localhost:4321/
┃ Network  use --host to expose

Open your browser and go to http://localhost:4321. You should see your Astro starter page — a clean, minimal page confirming everything works.

Accessing Astro from a Remote Server

If you are running this on a remote Ubuntu VPS, expose the dev server to your network with the --host flag:

npm run dev -- --host 0.0.0.0

Then access it at http://YOUR_SERVER_IP:4321. Make sure your firewall allows port 4321:

sudo ufw allow 4321

To stop the dev server at any time, press Ctrl + C in the terminal.

Step 5: Understanding the Astro Project Structure

Before you start editing files, take five minutes to understand what the CLI wizard generated. This knowledge will save you significant time as your project grows.

my-astro-project/
├── public/               ← Static assets (images, fonts, favicon, robots.txt)
├── src/
│   ├── components/       ← Reusable UI components (.astro, .jsx, .vue, .svelte)
│   ├── layouts/          ← Page templates shared across multiple pages
│   ├── pages/            ← File-based routing (index.astro = homepage at /)
│   └── styles/           ← Global CSS or Sass files
├── astro.config.mjs      ← Main Astro configuration file
├── package.json          ← Project dependencies and npm scripts
└── tsconfig.json         ← TypeScript configuration

Key Folders Explained

src/pages/ is where Astro’s file-based router lives. Every .astro, .md, or .html file you create here automatically becomes a route. For example, src/pages/about.astro becomes yoursite.com/about — no router configuration required.

public/ holds static assets that Astro copies directly to the final build without processing. Use it for favicons, PDFs, robots.txt, and any image you do not want Astro to optimize.

src/components/ is for reusable UI pieces — navigation bars, cards, buttons. These are not pages, so they do not become routes. You import them into pages and layouts.

The astro.config.mjs File

astro.config.mjs is your project’s central control panel. You configure integrations, build options, the dev server port, output mode (static vs. SSR), and more from this single file.

Step 6: Build Your Project for Production

When you are ready to deploy, generate the production build:

npm run build

Astro compiles all your .astro files into optimized, static HTML inside a dist/ folder at your project root. This output is what you upload to your hosting provider.

Previewing Your Production Build

Before deploying, always preview the production build to catch issues that do not appear in dev mode:

npm run preview

Astro serves the dist/ folder locally at http://localhost:4321. What you see here is exactly what users will experience in production.

Where to Deploy Your Astro Site

The dist/ folder is a fully self-contained static website. You can deploy it to:

• Cloudflare Pages — native Astro support, optimized since Cloudflare’s January 2026 partnership with Astro
• Vercel — zero-config deployment with @astrojs/vercel adapter
• Netlify — drag-and-drop the dist/ folder or connect via Git
• Any static host — GitHub Pages, Surge, Render, or your own VPS via Nginx/Apache

Troubleshooting: Configure Astro on Ubuntu 24.04 — Common Errors

Even with a clean setup, you will occasionally hit errors. Here are the five most common issues and their exact fixes.

Error 1: command not found: node

Cause: NVM was installed, but the shell has not loaded it yet — common after a fresh install or new terminal session.

Fix: Manually source NVM into your current session:

source ~/.bashrc

If the problem persists, add the NVM loader lines to ~/.bashrc manually:

export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"

Then run source ~/.bashrc again and verify with node -v.

Error 2: Unsupported Node.js Version

Cause: You are running Node.js v19 or v21, which Astro explicitly does not support.

Fix: Switch to a supported version using NVM:

nvm install 20
nvm use 20
nvm alias default 20

Re-run npm create astro@latest after switching.

Error 3: EACCES permission denied on npm install

Cause: Someone previously ran npm with sudo, corrupting the cache or permissions in ~/.npm.

Fix: Never use sudo npm. Instead, fix the permissions:

sudo chown -R $(whoami) ~/.npm
sudo chown -R $(whoami) ~/.nvm

Error 4: Port 4321 Already in Use

Cause: Another process is using port 4321 — common if you left a previous dev server running in the background.

Fix (Option A): Find and kill the conflicting process:

sudo lsof -i :4321
kill -9 <PID>

Fix (Option B): Run Astro on a different port:

npm run dev -- --port 3000

Error 5: npm create astro Hangs or Times Out

Cause: Network issues, DNS problems, or a corporate firewall blocking npm registry access.

Fix: Test your connection first:

curl -I https://registry.npmjs.org

If blocked, configure npm to reset its registry:

npm config set registry https://registry.npmjs.org/

To increase timeout for slow connections:

npm config set fetch-retry-maxtimeout 60000

Congratulations! You have successfully installed Astro. Thanks for using this tutorial for installing Astro web framework on Ubuntu 24.04 LTS system. For additional help or useful information, we recommend you check the official Astro website.