How to Install Valkey for Beginners in 2026

Introduction

Valkey is an open-source fork of Redis, launched in 2024 by the Linux Foundation community to counter Redis's shift to RSAL/RSPL licensing. Unlike Redis 8+, Valkey stays under the permissive BSD-3 license, offers 100% Redis protocol compatibility, and is optimized for in-memory caching, queues, and fast databases.

Why use it in 2026? Companies are ditching paid Redis; Valkey delivers the same sub-millisecond performance, AOF/RDB persistence, and master-slave replication without vendor lock-in. Think of it as an ultra-fast vault for user sessions or game scores. This beginner tutorial takes you from installation to a Python client example, with 100% copy-paste code. By the end, you'll handle production data like a pro. (128 words)

Prerequisites

System: Ubuntu 22.04+, macOS Ventura+, or Windows with WSL2
Tools: curl, build-essential (Linux), Homebrew (Mac), Python 3.10+
Knowledge: Basic terminal and JSON
Time: 15 minutes

Installing Valkey via Package Manager

install.sh

#!/bin/bash

# Ubuntu/Debian
sudo apt update
sudo apt install -y valkey

# macOS with Homebrew
# brew install valkey

# Verification
echo "Version installée :"
valkey-server --version
valkey-cli --version

This script installs Valkey using your system's native package manager—the simplest option for beginners. On Ubuntu, apt grabs the stable version; on Mac, uncomment the Homebrew line. Always check versions for compatibility. Skip source builds unless you need cutting-edge features.

Verification and First Startup

Run the installation script. You'll see the version (e.g., 8.0+). Valkey doesn't start automatically. Use systemctl to manage the systemd service on Linux.

Starting the Valkey Server

start-valkey.sh

#!/bin/bash

# Start in daemon mode (background)
sudo systemctl start valkey-server
sudo systemctl enable valkey-server  # Auto-start on boot

# Check status
sudo systemctl status valkey-server

# Or manual start (dev/test)
# valkey-server --port 6379 --daemonize yes

This code enables the systemd service for persistent startup, perfect for production. enable ensures auto-restart on boot. For local testing, use --daemonize yes. On Mac/Windows, adapt with brew services start valkey. Default port: 6379.

Connecting and Basic Commands

Connect via CLI. Test with PING to confirm: expect PONG. Store and retrieve like a giant dictionary.

Essential CLI Commands

valkey-cli-basics.txt

valkey-cli

PING
SET user:42 "Alice" EX 3600  # Key TTL 1h
GET user:42
DEL user:42

# List keys
KEYS *

# Server info
INFO server
EXIT

These commands cover the essentials: SET with TTL for auto-expiration (like a cookie), GET for reading, DEL for deletion. KEYS * lists everything (fine for dev, slow in prod). INFO shows stats. Copy-paste into valkey-cli for instant testing.

Custom Configuration

By default, Valkey listens on localhost:6379 with no password. Create a config file for production: bind, requirepass, persistence.

Valkey Configuration File

valkey.conf

# /etc/valkey/valkey.conf (copy-paste and adapt)
port 6379
bind 127.0.0.1
requirepass "your_password_here"

# RDB persistence (snapshots)
save 900 1
save 300 10
save 60 10000

dir /var/lib/valkey/
dbfilename dump.rdb

# Logs
logfile /var/log/valkey/valkey.log

# Max memory (limit)
maxmemory 256mb
maxmemory-policy allkeys-lru

This full config secures access (local bind + password), enables RDB persistence (auto-snapshots), and caps RAM at 256MB with LRU eviction (prevents OOM). Edit /etc/valkey/valkey.conf, then sudo systemctl restart valkey-server. Test CLI with -a pass.

Restart with Config and Auth Test

restart-with-config.sh

#!/bin/bash

sudo cp valkey.conf /etc/valkey/valkey.conf
sudo systemctl restart valkey-server
sudo systemctl status valkey-server

# Test with auth
valkey-cli -a "your_password_here" ping
valkey-cli -a "your_password_here" CONFIG GET requirepass

Copies the config and restarts the service. Tests auth with -a. If CONFIG GET returns the password (masked), it's good. Common error: forgetting to restart after editing the config.

Using with a Python Client

Valkey works with Redis clients. Install redis-py (same API).

Complete Python Client Example

valkey_client.py

import redis

# Connection (adapt host/port/pass)
r = redis.Redis(host='localhost', port=6379, password='your_password_here', decode_responses=True)

# Test
r.ping()
print('PONG')

# Store list (queue)
r.lpush('tasks', 'task1')
r.lpush('tasks', 'task2')
print(r.lrange('tasks', 0, -1))

# User hash
r.hset('user:42', mapping={'name': 'Alice', 'age': 30})
print(r.hgetall('user:42'))

# Expiration
r.set('temp', 'value', ex=10)
print(r.get('temp'))

import time
time.sleep(11)
print('After expiration:', r.get('temp'))  # None

r.close()

This full script demos ping, lists (LPUSH/LRANGE for queues), hashes (HSET/HGETALL for objects), and TTL. decode_responses=True handles strings nicely. Run pip install redis first. Ideal for Flask/Django integration.

Best Practices

Always secure: Use requirepass + bind 127.0.0.1 or firewall; add TLS in prod.
Limit memory: maxmemory + LRU/volatile-lru policy to avoid crashes.
Hybrid persistence: RDB for backups + AOF for durability (appendonly yes).
Structured keys: user:42:name instead of name to avoid collisions.
Monitoring: INFO + Prometheus exporter; scale with sentinels/cluster.

Common Errors to Avoid

Forgot password: CLI fails without -a pass; clients timeout.
KEYS * in prod: Blocks server (millions of keys); use SCAN instead.
No maxmemory: Eats all RAM, OOM killer terminates process.
Ignoring persistence: Disabled RDB/AOF = data loss on restart.

Next Steps

Official docs: valkey.io
Clustering: Advanced tutorial on sharding.
Alternatives: Dragonfly (compatible, faster).

Check out our Learni NoSQL training courses to master Valkey for production.

How to Install and Use Valkey for Beginners in 2026