macOS | Installation

The install script installs surreal, the SurrealDB command-line tool, and the database with it. surreal installs, updates and runs the database as a component, so surreal db start works from then on without a network connection. Homebrew is also available.

Installing with the install script

The install script downloads surreal and the database for your platform and CPU type, checks each download against its published SHA-256, and installs surreal into /usr/local/bin. If that folder is not writable, it installs into ~/.surrealdb and prints the PATH line to add.

curl -sSf https://install.surrealdb.com | sh

Pass options to the script after sh -s --. The database is installed by default; --no-db installs surreal alone, and the database installs on first use instead.

curl -sSf https://install.surrealdb.com | sh -s -- --no-db

See Install the SurrealDB CLI for every option, including the SURREAL_CLI_INSTALL_DB environment variable and installing the Cloud component alongside.

Installing a specific version of the database

Use -v or --version to install and pin a database release.

curl -sSf https://install.surrealdb.com | sh -s -- --version <version>

Updating

Once installed, surreal upgrades itself and every installed component. The database stays on its current major line.

surreal upgrade

To move the database to another release, name it: surreal upgrade db@<version>. See Managing components.

Installing with Homebrew

The Homebrew formula installs the database as a single surreal executable.

brew install surrealdb/tap/surreal

To update to the latest stable version (v3.3.4):

brew upgrade surrealdb/tap/surreal

Note

The Homebrew formula installs the database binary directly, so there is no surreal db prefix and no component management: run the database commands without db (for example surreal start), and update through Homebrew. To get surreal db <command>, surreal upgrade and the other components, use the install script. The install script leaves a surreal that Homebrew owns alone, so remove the formula first or install into another folder.

Confirming the installation

Run the following command to check that the database component runs.

surreal db version

Sample output

3.3.4 for macos on aarch64

To list surreal and every component with the version that runs, use surreal version.