GETTING STARTED
Installation
Install elizaOS on macOS, Linux, or Windows
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
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
Troubleshooting
Node.js issues
Node.js issues
Check if Node.js is installed and what version:If you get “command not found”:If you have version conflicts:
Terminal
- Node.js is not installed. Download and install from nodejs.org
- You need to upgrade. Use a Node.js version manager for easy switching:
Terminal
- Clear npm cache:
npm cache clean --force - Consider a fresh Node.js installation if switching from older versions
Bun issues
Bun issues
Check if Bun is installed and what version:If you get “command not found”:If you have version conflicts:
Terminal
- Bun is not installed. Install from bun.sh
Terminal
- Clear Bun cache:
bun pm cache rm - Restart your terminal after installation
- Verify installation:
bun --version
Windows Installation Issues
Windows Installation Issues
If you’re installing elizaOS natively on Windows (not using WSL2), follow these steps ( or watch the tutorial video here):Step 1: Install Git BashStep 6: Install elizaOS CLICommon Windows-specific issues:
- Download and install Git for Windows which includes Git Bash
- Important: Use Git Bash as your terminal, not PowerShell or Command Prompt
- Download and install Node.js for Windows
- Install version 23.3 or higher
- Open PowerShell as Administrator
- Run this command to add Node to your bash profile:
- Close and restart Git Bash for changes to take effect
- In Git Bash, run:
Git Bash
- You should see your Node.js version
- In Git Bash, run:
Git Bash
- In Git Bash, run:
Git Bash
- If
nodecommand 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
CLI Installation Issues
CLI Installation Issues
If elizaOS CLI fails to install:
- Clear Bun cache:
bun pm cache rm - Try reinstalling:
bun i -g @elizaos/cli
- The CLI may not be in your PATH. Add Bun’s global bin directory to PATH:
Terminal
- Then restart your terminal or run
source ~/.bashrc(or~/.zshrc)
- macOS/Linux: Use
sudo bun i -g @elizaos/cli - Windows: Run Git Bash as Administrator