Skip to main content

Databases · Beginner · 12 min

How to Install Valkey 9.1 (a Redis-Compatible Cache) on Ubuntu 26.04

By Padding · Updated 15 Nov 2026
Ubuntu 26.04.1 LTS · Valkey 9.1

You will install Valkey 9.1 from the project's official binary release, run it as its own user with a password and a memory limit, and use it as a cache from the command line.

On this page

Valkey is an in-memory data store. Apps use it as a cache, a session store, a rate limiter and a small queue, because reading a value from memory takes microseconds. It began as a fork of Redis 7.2 and is developed under the Linux Foundation. It speaks the same protocol, so Redis client libraries and the Redis commands you already know work against it unchanged.

Ubuntu 26.04 carries Valkey 9.0 in its own archive (valkey-server and valkey-tools). This tutorial installs Valkey 9.1.3 from the project's release builds instead, so you get the current minor version. If an older, apt-managed version is fine for you, sudo apt install valkey-server valkey-tools is a shorter route and sets up its own service.

You will download and check the release, create a service user and a config file, run the server under systemd, and try the commands you will use most. A Valkey server with no password and a public address gets found and abused within hours, so the config in this tutorial listens on the local machine only and requires a password.

Step 1 · Download and check the release

Valkey publishes ready-built binaries with a SHA-256 checksum next to each file. The file name carries your CPU architecture, so pick it from what the machine reports:

Bash
case "$(uname -m)" in
  x86_64) ARCH=x86_64 ;;
  aarch64) ARCH=arm64 ;;
  *) echo "Unsupported architecture: $(uname -m)" >&2; false ;;
esac
VER=9.1.3
cd /tmp
curl -fsSLO "https://download.valkey.io/releases/valkey-$VER-noble-$ARCH.tar.gz"
curl -fsSLO "https://download.valkey.io/releases/valkey-$VER-noble-$ARCH.tar.gz.sha256"
sha256sum -c "valkey-$VER-noble-$ARCH.tar.gz.sha256"

The last command prints valkey-9.1.3-noble-<arch>.tar.gz: OK. If it says FAILED, delete both files and download again. Do not install a file that fails the check. Note what the check proves: the checksum comes from the same site as the download, so it catches a damaged or truncated file, but it does not prove who published it. For that, compare the checksum with the one on the release page at github.com/valkey-io/valkey. The noble in the name is the Ubuntu 24.04 build, which runs on 26.04 without changes, because both use a compatible C library.

Unpack it and copy the programs into /usr/local/bin:

Bash
cd /tmp
tar xzf "valkey-$VER-noble-$ARCH.tar.gz"
sudo install -m 0755 "valkey-$VER-noble-$ARCH"/bin/valkey-* /usr/local/bin/

The install command copies the files and sets their mode in one step.

A tarball you install by hand is not tracked by apt, so apt upgrade will never update it and security fixes will not arrive on their own. Watch the Valkey release announcements, and upgrade by setting VER to the new version, repeating the download, check, unpack and install commands above, and then restarting the service with sudo systemctl restart valkey. Your config and data are not touched.

Check it worked

Bash
valkey-server --version
valkey-cli --version

The first line starts with Valkey server v=9.1.3, and the second reads valkey-cli 9.1.3. If your shell cannot find the commands, run hash -r and try again.

Step 2 · Create a service user and folders

Run the server as a user that owns nothing else on the machine. If the server is ever compromised, that limits what the attacker can touch.

Bash
sudo useradd --system --home-dir /var/lib/valkey --create-home --shell /usr/sbin/nologin valkey
sudo mkdir -p /etc/valkey
sudo chown root:valkey /etc/valkey
sudo chmod 750 /etc/valkey

/var/lib/valkey holds the data files, and /etc/valkey holds the config. The group valkey can read the config folder, and nobody else can.

Step 3 · Write a safe configuration

Create the config. It is a short file, and every setting you leave out keeps its default. This first command does not contain the password yet:

Create the file empty first, owned by root and readable by the valkey group only, so the password never sits in a world-readable file:

Bash
sudo install -m 640 -o root -g valkey /dev/null /etc/valkey/valkey.conf
sudo tee /etc/valkey/valkey.conf > /dev/null <<'CONF'
# Listen on this machine only. Open other interfaces only on purpose.
bind 127.0.0.1 -::1
port 6379
protected-mode yes

# Data lives here. Valkey writes snapshots and the append-only log into this folder.
dir /var/lib/valkey
appendonly yes

# A cache must not eat all the memory. When full, evict the least recently used keys.
maxmemory 256mb
maxmemory-policy allkeys-lru

# systemd captures the log, so write to standard output.
logfile ""
daemonize no
CONF

Add a random password. The command generates it on the server and appends it to the file without it appearing in your shell history or in the process list:

Bash
printf 'requirepass %s\n' "$(openssl rand -hex 24)" | sudo tee -a /etc/valkey/valkey.conf > /dev/null

The file holds a secret and was private from the first byte: it is readable only by root and the valkey group. Pick maxmemory to suit the machine: leave room for the operating system and your app, which usually means no more than half of the RAM on a shared server. allkeys-lru suits a cache. If Valkey holds data you cannot rebuild, such as a job queue, use maxmemory-policy noeviction, which makes writes fail when memory is full instead of deleting data.

Check it worked

Bash
sudo grep -c '^requirepass ' /etc/valkey/valkey.conf
ls -l /etc/valkey/valkey.conf

The first command prints 1, and the listing shows mode -rw-r----- with owner root and group valkey.

Step 4 · Run Valkey as a systemd service

Create a unit file so the server starts at boot and restarts if it crashes:

Bash
sudo tee /etc/systemd/system/valkey.service > /dev/null <<'UNIT'
[Unit]
Description=Valkey in-memory data store
After=network.target

[Service]
User=valkey
Group=valkey
ExecStart=/usr/local/bin/valkey-server /etc/valkey/valkey.conf
Restart=on-failure
LimitNOFILE=65535
NoNewPrivileges=yes
ProtectSystem=full
ProtectHome=yes
PrivateTmp=yes
ReadWritePaths=/var/lib/valkey

[Install]
WantedBy=multi-user.target
UNIT

Start it and turn it on for every boot:

Bash
sudo systemctl daemon-reload
sudo systemctl enable --now valkey
systemctl status valkey

The status shows active (running). Press q to leave it. Read the server log with journalctl -u valkey.

Troubleshooting

  • Failed to start valkey.service with status=217/USER: the valkey user does not exist yet. Go back to the service user step.
  • Can't open the log file or Permission denied on /var/lib/valkey: check ls -ld /var/lib/valkey, which should be owned by valkey.
  • Could not create server TCP listening socket *:6379: bind: Address already in use: another Valkey or Redis is already listening. Find it with sudo ss -ltnp | grep 6379.
  • FATAL CONFIG FILE ERROR: the log names the line number. Check for a typo in the setting on that line.

Step 5 · Connect and run commands

Connect with the command-line client. It reads the password from the VALKEYCLI_AUTH environment variable, so you never type it on the command line, where ps could show it. Load the password from the config file into the variable for this shell session:

Bash
export VALKEYCLI_AUTH="$(sudo awk '$1 == "requirepass" {print $2}' /etc/valkey/valkey.conf)"
valkey-cli ping

The reply is PONG. Without the password, a command is refused:

Bash
env -u VALKEYCLI_AUTH valkey-cli ping

The reply is NOAUTH Authentication required., which tells you the password check works.

Now store and read back a value, then give a key a lifetime. Keys with a time to live vanish by themselves, which is how a cache stays fresh:

Bash
valkey-cli SET greeting "hello from valkey"
valkey-cli GET greeting
valkey-cli SET session:42 "user=ada" EX 60
valkey-cli TTL session:42
valkey-cli INCR page:views
valkey-cli INCR page:views
valkey-cli HSET user:1 name Ada role admin
valkey-cli HGETALL user:1
valkey-cli DEL greeting

SET replies OK and GET prints the stored text. TTL prints the seconds left, a number at or below 60. INCR replies 1 and then 2, and creates the counter on first use. HGETALL lists the hash's field and value pairs on alternate lines.

Check it worked

Ask the server about itself:

Bash
valkey-cli INFO server | grep -E '^(valkey_version|tcp_port|config_file)'
valkey-cli INFO memory | grep -E '^(used_memory_human|maxmemory_human|maxmemory_policy)'

The output includes valkey_version:9.1.3, tcp_port:6379, maxmemory_human:256.00M and maxmemory_policy:allkeys-lru.

Use SCAN rather than KEYS * to list keys. KEYS blocks the server while it walks every key, which on a large cache stalls every client:

Bash
valkey-cli --scan --pattern 'session:*'

Step 6 · Know what gets saved to disk

Valkey keeps everything in memory, and writes to disk so data survives a restart. The config enabled the append-only file (appendonly yes), which logs every write. By default it is flushed to disk once a second, so a crash can lose about a second of writes. The server also takes periodic snapshots to dump.rdb in the data folder.

Bash
valkey-cli BGSAVE
sleep 2
sudo ls -l /var/lib/valkey

BGSAVE replies Background saving started. The listing shows a dump.rdb file, and a folder named appendonlydir that holds the append-only log. Copy these files for a backup, or run valkey-cli BGSAVE and then copy dump.rdb.

The server log may warn Memory overcommit must be enabled!. Without that kernel setting, a background save can fail when memory is tight. Turn it on, and keep it across reboots:

Bash
echo 'vm.overcommit_memory = 1' | sudo tee /etc/sysctl.d/99-valkey.conf
sudo sysctl --system

If you only use Valkey as a cache and can lose its contents, set appendonly no in the config and restart for less disk traffic.

Step 7 · Keep it private

Valkey has no per-connection encryption by default and is designed for a trusted network. Two rules keep it safe:

  • Keep bind 127.0.0.1 -::1 unless another machine must connect. If one must, bind to the server's private address, never to 0.0.0.0 on a public interface.
  • Keep port 6379 closed in your firewall to everyone but your app servers.

Check what the server is listening on:

Bash
sudo ss -ltnp | grep 6379

The address column reads 127.0.0.1:6379 and [::1]:6379, so the server is reachable only from the machine itself.

Next steps

  • Close the ports you do not use: /tutorials/set-up-ufw-firewall-ubuntu-26-04.
  • Harden how you log in to the server: /tutorials/harden-ssh-on-ubuntu-26-04.
  • Valkey's command reference and configuration guide are at valkey.io/commands and valkey.io/topics.

Need this done for you?

Padding does this work for growing companies, from the first diagnosis to a system that keeps working.

Platform Engineering

Get new tutorials

New tutorials, about twice a month.