This page installs the surreal command and, optionally, the components it runs. Pick one installation method; everything after it applies whichever you chose.
The install script puts the surreal launcher on your machine, then uses it to install the database as a component and pin it, so surreal db start works from then on with no network connection. The script checks every download against the SHA-256 published beside it, and installs nothing if a check fails.
Install on macOS and Linux
curl -sSf https://install.surrealdb.com | shThe script installs surreal into /usr/local/bin. If that folder is not writable it falls back to ~/.surrealdb, or asks where to install when you pass --interactive, and then prints the PATH line to add. It never edits your shell profile. The script is served as plain text, so you can open the same URL in a browser and read it before you run it.
Pass options after -s --, which is how sh forwards arguments to a script it reads from a pipe.
curl -sSf https://install.surrealdb.com | sh -s -- --no-db --with cloud--version, --nightly, --beta and --alpha choose the database release, so they apply only when the database is installed. The script refuses them together with --no-db.
Install on Windows
Run the PowerShell script from a normal or an elevated shell.
irm https://windows.surrealdb.com | iexThe script installs surreal.exe into C:\Program Files\SurrealDB from an elevated shell, and into %LOCALAPPDATA%\SurrealDB otherwise, and adds that folder to your user PATH. A folder you name yourself is not added to PATH.
irm | iex cannot pass options. To pass them, run the script as a script block.
& ([scriptblock]::Create((irm https://windows.surrealdb.com))) -NoDb -With cloudChoose whether to install the database
The database is installed by default. Choose explicitly with --db or --no-db (-Db or -NoDb on Windows), or with the SURREAL_CLI_INSTALL_DB environment variable for callers that cannot pass options, such as curl ... | sh in a Dockerfile or a CI step.
| Setting | Effect |
|---|---|
SURREAL_CLI_INSTALL_DB=1 | Install the database, as --db does |
SURREAL_CLI_INSTALL_DB=0 | Install surreal alone, as --no-db does |
curl -sSf https://install.surrealdb.com | SURREAL_CLI_INSTALL_DB=0 shA flag wins over the variable, and the last of --db, --no-db and --minimal wins over the others. Because the default may change, a script that needs one outcome should say so with a flag or the variable.
Without the database, surreal db <command> offers to install it the first time you run it, and surreal install db installs it at any time. Components installed this way follow the rules in Managing components.
Install more components
--with installs further components in the same step, through the launcher.
curl -sSf https://install.surrealdb.com | sh -s -- --with cloudWith surreal already installed, surreal install cloud does the same. Managing components covers versions, upgrading and pinning.
Confirm the installation
surreal version lists each component, the version that runs, and where it runs from.
surreal versionCOMPONENT VERSION SOURCE INSTALLED PATH
cli 0.1.0 cli /usr/local/bin/surreal
db 3.3.4 pinned 3.3.4 /home/you/.surrealdb/components/db/3.3.4/surreal-db
cloud 0.1.0 pinned 0.1.0 /home/you/.surrealdb/components/cloud/0.1.0/surreal-cloudsurreal --version prints the same information on a few lines, and surreal version --json prints it as one JSON document.
Where files go
The launcher keeps everything it installs in one folder, the SurrealDB home. It is ~/.surrealdb (%USERPROFILE%\.surrealdb on Windows) unless SURREAL_CLI_HOME names another folder. Each component version is a separate file under components/<name>/<version>/, which is what lets several versions sit side by side.
Other ways to install
Package managers
Homebrew, Chocolatey and Scoop install the database as a single surreal executable, and update it through the package manager. That executable is the database itself, not the launcher: it has no surreal db prefix and no component management, so run its commands without db and update it with the package manager. See the installation pages for macOS and Windows. The install script leaves a surreal that a package manager owns alone; remove the package first, or install into another folder.
Docker
The Docker image runs the database directly, so Docker examples use surreal start rather than surreal db start, and nothing inside the image installs or upgrades components. See Running with Docker.
A mirror
SURREAL_CLI_DOWNLOAD_ROOT replaces the download host, for an internal mirror. The mirror must publish the launcher under cli/launcher/, each component in its own folder beneath cli/, and the database at its root, in the same layout as https://download.surrealdb.com. The value is an http or https address with no user name, password, query or fragment.
Offline machines
SURREAL_CLI_OFFLINE=1 forbids every network request. A component that is already installed runs normally, and a missing one fails at once with the command that would install it. See Managing components.
Troubleshooting
A different surreal runs
A surreal earlier on your PATH, such as an older standalone database, runs instead of the launcher. The install script warns when it finds one. Remove the older executable, or put the launcher's folder first on PATH. surreal version shows the path each component runs from.