Installation Troubleshooting

Error: Python Version Too Old

⚠️

Error message: ERROR: openclaw requires Python >=3.10

Check your Python version and upgrade if needed:

python3 --version

# Ubuntu/Debian: install newer Python
sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt install python3.11 python3.11-venv

# macOS: upgrade via Homebrew
brew upgrade python@3.11

Error: pip Not Found

# Ubuntu/Debian
sudo apt install python3-pip

# Fedora
sudo dnf install python3-pip

# macOS
python3 -m ensurepip --upgrade

# Fallback: use python -m pip
python3 -m pip install openclaw

Error: Externally-Managed Environment (Ubuntu 22.04+)

⚠️

Error message: error: externally-managed-environment

Use a virtual environment (recommended):

python3 -m venv ~/.venvs/openclaw
source ~/.venvs/openclaw/bin/activate
pip install openclaw

Or override (not recommended for production):

pip install --break-system-packages openclaw

Error: Permission Denied

Never use sudo pip. Instead install for the current user:

pip install --user openclaw

# Make sure ~/.local/bin is in PATH
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Error: SSL Certificate Verification Failed

# Upgrade pip and certifi first
pip install --upgrade pip certifi

# Or specify trusted host as a last resort
pip install --trusted-host pypi.org --trusted-host files.pythonhosted.org openclaw

Error: openclaw Command Not Found

# Find where it was installed
python3 -m site --user-bin
which openclaw

# Add Python scripts to PATH (Linux/macOS)
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# Windows PowerShell: add Scripts dir to PATH
$env:PATH += ";$env:APPDATA\Python\Python311\Scripts"

Error: Conflicting Dependencies

# Use a fresh virtual environment
python3 -m venv ~/.venvs/openclaw-clean
source ~/.venvs/openclaw-clean/bin/activate
pip install openclaw

# See full dependency tree
pip show openclaw

Debug: Verbose Install Output

If none of the above solves your issue, collect verbose output and report it:

pip install openclaw -v 2>&1 | tee install-debug.log
python3 -m pip install openclaw --verbose 2>&1 | tee install-debug.log

Open an issue at the GitHub issues page and attach the log file.

💡

See Also

Step-by-Step Diagnosis

Run these commands in order to pinpoint the problem:

# Step 1: Confirm Python version (need 3.10+)
python --version
python3 --version

# Step 2: Confirm pip is working
pip --version

# Step 3: Try install with verbose output
pip install openclaw -v 2>&1 | tail -30

# Step 4: Try with --user flag (avoids system permission issues)
pip install --user openclaw

# Step 5: Check if binary is in PATH
which openclaw           # Linux/macOS
where openclaw           # Windows CMD
Get-Command openclaw     # Windows PowerShell

PATH Issues (Most Common Cause)

# Linux/macOS — add pip user bin to PATH
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# macOS with Homebrew Python
echo 'export PATH="$(brew --prefix)/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# Windows PowerShell — add Scripts to PATH
$UserScripts = "$env:APPDATA\Python\Python3xx\Scripts"
[Environment]::SetEnvironmentVariable("PATH", "$env:PATH;$UserScripts", "User")

Platform-Specific Fixes

Windows: "openclaw is not recognized"

# Find where openclaw was installed
pip show openclaw | Select-String Location
# Location: C:\Users\YourName\AppData\Local\Programs\Python\Python311\Lib\site-packages

# The CLI binary is in the Scripts folder:
# C:\Users\YourName\AppData\Local\Programs\Python\Python311\Scripts\openclaw.exe

# Add to PATH permanently:
[Environment]::SetEnvironmentVariable(
  "PATH",
  "$env:PATH;$env:LOCALAPPDATA\Programs\Python\Python311\Scripts",
  "User"
)
# Restart PowerShell after this

macOS/Linux: "Permission denied"

# Never use sudo with pip — use --user instead
pip install --user openclaw

# Or use a virtual environment (recommended)
python3 -m venv ~/.venv/openclaw
source ~/.venv/openclaw/bin/activate
pip install openclaw

SSL Certificate Errors (Corporate/Proxy Networks)

pip install openclaw --trusted-host pypi.org --trusted-host files.pythonhosted.org

# If behind a proxy:
pip install openclaw   --proxy http://user:pass@proxy.company.com:8080

Dependency Conflicts

# Create a clean virtual environment to isolate dependencies
python3 -m venv ~/.venv/openclaw-clean --clear
source ~/.venv/openclaw-clean/bin/activate
pip install openclaw

# Check for conflicting packages
pip check

Quick Fix Checklist

Before digging into specific errors, run through these five checks — they resolve ~80% of installation problems:

#	Check	Command	Expected
1	Python version is 3.10+	`python --version`	`Python 3.10.x` or higher
2	pip is up-to-date	`pip install --upgrade pip`	No errors
3	Virtual environment is active	`which openclaw` or `where openclaw`	Path inside your venv folder
4	API key is set	`echo $OPENAI_API_KEY`	Starts with `sk-`
5	Doctor check passes	`openclaw doctor`	All green ✓

If all five pass and you still have problems, enable verbose output: openclaw --verbose doctor for a full diagnostic report. See also Common Errors for runtime (not install-time) issues.

← Server Installation Installation Overview →