installation.mdx

title	Installation
description	Install elizaOS on macOS, Linux, or Windows

export const BunIcon = ( );

export const NodeIcon = ( );

Prerequisites

Before installing elizaOS, ensure you have the following:

• Node.js 23.3+: Install Node.js version 23.3 or higher from nodejs.org
• Bun: Install the latest Bun runtime from bun.sh

**Windows Users:** You have two options for installing elizaOS:

Option 1: Use WSL2 (Windows Subsystem for Linux) for a Linux environment on Windows

Option 2: Install natively on Windows, but first install Git Bash and use it as your terminal for installing and running Node.js, Bun, and the elizaOS CLI

Installing elizaOS

Once you have Node.js and Bun installed, you can install the elizaOS CLI globally:

bun i -g @elizaos/cli

This installs the elizaos command globally on your system, allowing you to create and manage elizaOS projects from anywhere.

**Important:** You don't need to clone the elizaOS repository to build agents. The CLI handles everything for you. Only clone the monorepo if you're [contributing to core](/guides/contribute-to-core).

Verify Installation

After installation, verify that elizaOS CLI is properly installed:

elizaos --version

You should see the version number of the installed CLI.

Troubleshooting

**Check if Node.js is installed and what version:** ```bash Terminal node --version ```

**If you get "command not found":**
- Node.js is not installed. Download and install from [nodejs.org](https://nodejs.org/)

**If you get a version lower than v23.3.0:**
- You need to upgrade. Use a Node.js version manager for easy switching:
```bash Terminal
# Install nvm (macOS/Linux)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# Install and use Node.js 23.3
nvm install 23.3
nvm use 23.3
```

**If you have version conflicts:**
- Clear npm cache: `npm cache clean --force`
- Consider a fresh Node.js installation if switching from older versions

Alternative version managers: [fnm](https://github.com/Schniz/fnm) (faster) or [volta](https://volta.sh/)

**Check if Bun is installed and what version:** ```bash Terminal bun --version ```

**If you get "command not found":**
- Bun is not installed. Install from [bun.sh](https://bun.sh/)
```bash Terminal
# Install Bun (macOS/Linux)
curl -fsSL https://bun.sh/install | bash

# Windows
powershell -c "irm bun.sh/install.ps1 | iex"
```

**If you have version conflicts:**
- Clear Bun cache: `bun pm cache rm`
- Restart your terminal after installation
- Verify installation: `bun --version`

If you're installing elizaOS natively on Windows (not using WSL2), follow these steps ( or watch the tutorial video [here](https://youtu.be/QiRg0C1zDjU?si=akR0bIbbiWYVxEQd)):

**Step 1: Install Git Bash**
- Download and install [Git for Windows](https://git-scm.com/downloads) which includes Git Bash
- **Important:** Use Git Bash as your terminal, not PowerShell or Command Prompt

**Step 2: Install Node.js**
- Download and install [Node.js for Windows](https://nodejs.org/en/download/)
- Install version 23.3 or higher

**Step 3: Add Node to your PATH for Git Bash**
- Open PowerShell **as Administrator**
- Run this command to add Node to your bash profile:
```powershell
echo 'export PATH=$PATH:"/c/Program Files/nodejs"' >> ~/.bashrc
```
- Close and restart Git Bash for changes to take effect

**Step 4: Verify Node installation**
- In Git Bash, run:
```bash Git Bash
node --version
```
- You should see your Node.js version

**Step 5: Install Bun**
- In Git Bash, run:
```bash Git Bash
powershell -c "irm bun.sh/install.ps1 | iex"
```

**Step 6: Install elizaOS CLI**
- In Git Bash, run:
```bash Git Bash
bun install -g @elizaos/cli
```

**Common Windows-specific issues:**
- If `node` command not found: Node wasn't added to PATH correctly, restart Git Bash
- If scripts fail: Make sure you're using Git Bash, not PowerShell or CMD
- If permission errors: Run Git Bash as Administrator when installing global packages

**If elizaOS CLI fails to install:** - Clear Bun cache: `bun pm cache rm` - Try reinstalling: `bun i -g @elizaos/cli`

**If "command not found" after installation:**
- The CLI may not be in your PATH. Add Bun's global bin directory to PATH:
```bash Terminal
# Add to ~/.bashrc or ~/.zshrc
export PATH="$HOME/.bun/bin:$PATH"
```
- Then restart your terminal or run `source ~/.bashrc` (or `~/.zshrc`)

**Permission errors during global install:**
- macOS/Linux: Use `sudo bun i -g @elizaos/cli`
- Windows: Run Git Bash as Administrator

**If `elizaos --version` shows an older version despite installing a newer one:**

This usually happens when elizaOS CLI was installed with different package managers (npm, pnpm, bun), creating version conflicts.

**Solution - Clean install with bun only:**
```bash Terminal
# Remove from all package managers
bun remove -g @elizaos/cli
npm uninstall -g @elizaos/cli
pnpm remove -g @elizaos/cli

# Verify removal
which elizaos
# Should return nothing or "not found"

# Fresh install with bun only
bun i -g @elizaos/cli

# Verify correct version
elizaos --version
```

**If you get a PATH warning:**
```bash Terminal
# Add bun's global bin to your PATH
echo 'export PATH="$HOME/.bun/bin:$PATH"' >> ~/.bashrc
# or for zsh
echo 'export PATH="$HOME/.bun/bin:$PATH"' >> ~/.zshrc

# Reload your shell configuration
source ~/.bashrc  # or source ~/.zshrc
```

**Important:** Always use bun for elizaOS CLI installation to avoid conflicts. Don't mix package managers.