To install SurrealDB on Ubuntu 26.04 or 24.04, run the official Linux installer as your regular user. SurrealDB stores records you can query with SurrealQL, its SQL-style query language.
You’ll run a local database on disk, add a task, and check that the task survives a restart.
- Use Ubuntu 26.04 LTS or 24.04 LTS with Bash and internet access. You need sudo for Ubuntu packages only.
- Check for a 64-bit
x86_64oraarch64system. - Use a fresh practice directory. The examples bind to localhost for local development.
On this page
ToggleInstall SurrealDB
Check the release and CPU architecture, then install curl and the certificate bundle used for HTTPS. On a minimal image, install lsb-release if the first command is missing.
lsb_release -a
uname -m
sudo apt update && sudo apt install -y curl ca-certificates
Run the installer as your normal user. On a standard Ubuntu setup, your account cannot write to /usr/local/bin, so the installer falls back to ~/.surrealdb. The installer checks the downloads against published SHA-256 checksums and leaves your shell profiles untouched.
curl -sSf https://install.surrealdb.com | sh
If the installer used ~/.surrealdb, add the first line below once at the end of ~/.bashrc. The remaining lines reload Bash settings and verify the installation.
export PATH="$HOME/.surrealdb:$PATH"
Run these commands in your terminal after saving the file. Expect the database component in the list and a database version such as 4.0.1, the stable release at review.
source ~/.bashrc
surreal list
surreal db version
Start a persistent local server
SurrealDB 4.0 uses SurrealKV 1.0, its native Rust storage engine, for this on-disk database. The memory backend is useful for disposable experiments because records disappear when the process stops.
Open a Bash terminal and enter a strong, unique practice password when prompted. Reading it into a variable keeps it out of shell history. The process can still expose a password supplied as a command-line argument to other local users with sufficient access.
mkdir -p "$HOME/surrealdb-practice"
cd "$HOME/surrealdb-practice"
read -r -s -p 'SurrealDB password: ' SURREALDB_PASSWORD
printf '\n'
surreal db start --bind 127.0.0.1:8000 --username root --password "$SURREALDB_PASSWORD" surrealkv://project_data
unset SURREALDB_PASSWORD
Keep this terminal open. Binding to 127.0.0.1 limits connections to this computer. The username and password initialize a SurrealDB root account only when the datastore is new. Starting the same directory with different credentials leaves its existing password in place.
Run your first SurrealQL queries
Check that the server is ready, then enter the same password. The interactive shell opens at main/main> by default with a new v4 datastore.
surreal db is-ready --endpoint http://127.0.0.1:8000
read -r -s -p 'SurrealDB password: ' SURREALDB_PASSWORD
printf '\n'
surreal db sql --endpoint http://127.0.0.1:8000 --username root --password "$SURREALDB_PASSWORD" --pretty
unset SURREALDB_PASSWORD
A namespace groups databases. A database holds tables and records. Define workspace first, then create the tracker database inside it. Enter these statements at the SurrealQL prompt.
DEFINE NAMESPACE IF NOT EXISTS workspace;
USE NS workspace;
DEFINE DATABASE IF NOT EXISTS tracker;
USE NS workspace DB tracker;
CREATE task:install SET title = "Install SurrealDB", done = false;
SELECT * FROM task:install;
The result should include the record ID task:install and done: false. If you repeat the example, query or update the existing record instead of creating it again.
Update the record by ID, then read it again. The done field should now be true.
UPDATE task:install SET done = true;
SELECT * FROM task:install;
Verify the data survives a restart
Press Ctrl+D at the SQL prompt to return to Bash. In the server terminal, press Ctrl+C, then start it again from the same directory. The existing datastore already contains the root account.
cd "$HOME/surrealdb-practice"
surreal db start --bind 127.0.0.1:8000 surrealkv://project_data
Reconnect using the commands in the query section. After the SQL prompt opens, select the same namespace and database. Seeing done: true confirms that the update survived the restart.
USE NS workspace DB tracker;
SELECT * FROM task:install;
Back up, update and remove SurrealDB
In the second terminal, exit SurrealQL first. Export the tracker database to a separate, timestamped file and check that the export is nonempty. Store a copy separately if you plan to remove the practice directory. A database export covers the selected database. Keep the root credentials separately and test restores before relying on a backup.
umask 077
backup="$(mktemp "$HOME/surreal-tracker-$(date +%F)-XXXXXX.surql")"
read -r -s -p 'SurrealDB password: ' SURREALDB_PASSWORD
printf '\n'
surreal db export --endpoint http://127.0.0.1:8000 --username root --password "$SURREALDB_PASSWORD" --namespace workspace --database tracker "$backup" &&
test -s "$backup" && printf 'Export saved to %s\n' "$backup"
unset SURREALDB_PASSWORD
After exporting your data, stop the server before upgrading. To update the launcher and installed components, run the first command. To update the database component only, run the second command instead. Check the database version afterward and restart from the same directory.
surreal upgrade
For the database component only, use this command.
surreal upgrade db
Confirm the version before restarting.
surreal db version
Export anything you want to keep and stop the server with Ctrl+C. Uninstall the database component from the launcher.
surreal uninstall db
For a dedicated per-user install, move ~/.surrealdb aside so you can recover it if it contains other Surreal components. If the destination already exists, choose a different name before running the command. Remove the PATH line you added to ~/.bashrc and open a fresh terminal. You can delete the moved folder once you have checked its contents.
mv -iT -- "$HOME/.surrealdb" "$HOME/.surrealdb-removed"
Your SurrealKV datastore is separate at ~/surrealdb-practice/project_data. Keep it for later or delete the project_data folder through your file manager after verifying your backup. Deleting it permanently removes its local records and accounts.
Troubleshoot common errors
Reload ~/.bashrc and check which executable Bash can see. If an older executable appears first, confirm that the per-user install directory is at the front of your PATH.
source ~/.bashrc
type -a surreal
Check which process is listening. If the port belongs to a service you need, choose another free port such as 8001. Use the new port for --bind and each client’s --endpoint.
ss -ltnp | grep 8000
For a refused connection, check that the first terminal still shows the running server and that your endpoint uses its port. For a login failure, enter the password used when the datastore was first initialized.
Frequently asked questions
Can I run SurrealDB without sudo?
Yes. You need sudo to install missing Ubuntu prerequisites. The official installer can put SurrealDB in your home directory, and the local server runs under your regular account.
Why does the SQL prompt show main/main?
Those are the default namespace and database on a new SurrealDB 4 datastore. Use USE NS workspace DB tracker; to switch to the project tracker after creating it.
Why did my tasks disappear after restarting?
Check that you started the SurrealKV server from the same working directory using surrealkv://project_data. Starting with memory or opening a different datastore gives you a different set of records.
Related Ubuntu guides
- How to check your Ubuntu version
- How to install and use curl on Ubuntu
- How to install and use ClickHouse on Ubuntu
Source: SurrealDB’s official Linux installation documentation.
