The install command fails

When the install command can’t finish, it stops with a line that starts with waycar: error:. Warnings start with waycar: and let the install continue. Find the message below to see what it means and how to fix it, then run the install command again:

curl -fsSL https://waycar.dev/install.sh | sh

Errors that stop the install

Message	What it means	Fix
neither herdr nor tmux found on PATH; install herdr (https://herdr.dev) or tmux 3.2 or later	The Host has no Backend Waycar can use.	Install herdr or tmux 3.2 or later. See Requirements.
herdr not found, and tmux … is too old; install herdr (https://herdr.dev) or tmux 3.2 or later	tmux is there but older than 3.2, and herdr isn’t.	Update tmux to 3.2 or later, or install herdr.
Node.js >= 20 required, found … at …	The Node.js Waycar found is too old.	Install Node 20 or later, for example with NodeSource or nvm.
node not found on PATH (…) or in nvm, fnm, Volta, asdf, mise, Homebrew, /usr/local/bin or ~/.local/bin; install Node.js >= 20	No Node.js anywhere Waycar looks.	Install Node 20 or later.
curl not found or tar not found	The command needs both to download and unpack the package.	Install curl and tar with your package manager.
sha256sum or shasum required to verify the download	Waycar can’t check the package’s checksum.	Install sha256sum (coreutils) or shasum.
download failed: …	The package didn’t download.	Check the Host’s internet connection and try again.
checksum mismatch for …	The downloaded package isn’t the one published with the script.	Run the command again. If it keeps failing, something between the Host and waycar.dev is changing the download.
… exists and is not the Waycar plugin; move it or set WAYCAR_PLUGIN_DIR	Something else lives in the install folder. Waycar never overwrites it.	Move that folder, or pick another one with WAYCAR_PLUGIN_DIR. See Install options.
WAYCAR_PLUGIN_DIR must be an absolute path	The custom install folder is relative.	Use a full path starting with /.
WAYCAR_PLUGIN_DIR must not contain a double quote, backslash or newline …	The folder name has a character Waycar can’t use.	Choose a folder without those characters.
unknown option: … (expected --tmux or --no-hooks)	The command got a flag it doesn’t know.	Use only --tmux or --no-hooks.
herdr plugin link failed or could not remove the existing waycar plugin	herdr refused to link or replace the Waycar plugin.	Run herdr plugin list to see what’s installed, remove the old waycar plugin by hand, then run the command again.
package is missing herdr-plugin.toml	The unpacked package is incomplete.	Run the command again.
WAYCAR_PLUGIN_SOURCE is not a directory: …, … is not the Waycar plugin (no herdr-plugin.toml with id "waycar"), npm not found; run npm ci in … first, or npm ci failed in the copy of …	Only with WAYCAR_PLUGIN_SOURCE: the local folder isn’t a usable Waycar plugin.	Point it at a checkout’s plugin/ folder or an unpacked package, and run npm ci there first.

Warnings

Message	What it means	Fix
herdr isn't running here; start it, then run: herdr plugin action invoke waycar.pair	The plugin installed, but the pairing QR needs a running herdr. Common when you install over SSH.	Start herdr, then run that command. See Pair with a Pairing Code.
warning: agent status hooks were not installed; retry: … hooks install	The plugin installed, but adding the Status Hooks failed.	Run the hooks install command it prints. See Waycar hooks for tmux.
…/.local/bin/waycar exists and is not a link; leaving it (run … instead)	Another file already uses the name waycar.	Run the full path it prints, or move the other file and run the install command again.
add …/.local/bin to your PATH to run waycar	The waycar command is installed but your shell can’t find it.	Add ~/.local/bin to your PATH in your shell profile.
tmux 3.2 or later not found (found …); agent status hooks not installed	You used --tmux and --no-hooks on a Host whose tmux is older than 3.2.	Update tmux to 3.2 or later and run the command again.
… exists and was not installed by Waycar; left unchanged	An omp, pi or opencode extension file with Waycar’s name already exists, and Waycar didn’t write it. From the hooks, the line starts with the agent’s name and error:.	If you don’t need that file, move it away, then run the command again.
pairing did not finish; run: … pair	waycar pair stopped with an error, for example Pairing cannot start because the Host has no SSH host key or no network address. Closing the Pairing Code yourself doesn’t print this.	Fix what the pairing screen reported (see Messages on the Host), then run the command it prints.

Still stuck?

Run the command again and keep the full output. See Get help and contact support.