​
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 WindowsOption 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:
Terminal
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.

​
Verify Installation

After installation, verify that elizaOS CLI is properly installed:
Terminal
elizaos --version
You should see the version number of the installed CLI.

​
Troubleshooting

Check if Node.js is installed and what version:
Terminal
node --version
If you get “command not found”:
  • Node.js is not installed. Download and install from 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:
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 (faster) or volta
Check if Bun is installed and what version:
Terminal
bun --version
If you get “command not found”:
  • Bun is not installed. Install from bun.sh
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):Step 1: Install Git Bash
  • Download and install Git for Windows which includes Git Bash
  • Important: Use Git Bash as your terminal, not PowerShell or Command Prompt
Step 2: Install Node.jsStep 3: Add Node to your PATH for Git Bash
  • Open PowerShell as Administrator
  • Run this command to add Node to your bash profile:
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:
Git Bash
node --version
  • You should see your Node.js version
Step 5: Install Bun
  • In Git Bash, run:
Git Bash
powershell -c "irm bun.sh/install.ps1 | iex"
Step 6: Install elizaOS CLI
  • In Git Bash, run:
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:
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