Valkey: The Open-Source Redis Fork Migration Guide

TL;DR — Quick Summary

Valkey is the Linux Foundation's open-source Redis fork. Install it, migrate from Redis with zero data loss, and configure clusters and Sentinel HA.

Valkey is the Linux Foundation’s open-source fork of Redis, created after Redis Ltd changed its license away from BSD in March 2024. If you run Redis in production and want to stay on a truly open-source, community-governed key-value store, this guide walks you through understanding Valkey, installing it, migrating from Redis with zero data loss, and operating clusters and Sentinel HA.

Why Valkey Exists

Redis was BSD-licensed from 2009 through early 2024. On March 20, 2024, Redis Ltd relicensed Redis under a dual SSPL/RSAL model — neither license is OSI-approved, meaning Redis is no longer open source by the standard definition. Cloud providers and contributors who had built on Redis’s open governance forked the last BSD-licensed release (7.2.4) within days.

The Linux Foundation accepted the fork as Valkey in April 2024, backed by Amazon Web Services, Google Cloud, Oracle, Ericsson, Snap, and many individual contributors. Valkey is governed under the Linux Foundation’s neutral, community-first model — the same umbrella as Linux, Kubernetes, and Node.js.

The practical result: Valkey tracks the Redis 7.2 codebase, is drop-in compatible, and receives new features (RDMA support, per-slot dict in cluster mode, dual-channel replication) that Redis OSS no longer ships.

Prerequisites

• A Linux server running Ubuntu 22.04+, Debian 12+, RHEL 9+, or any modern distro.
• Existing Redis 6.x or 7.x installation (if migrating).
• sudo access or root.
• Docker (optional, for the container path).

---

Installing Valkey

apt (Debian/Ubuntu)

curl -fsSL https://packages.valkey.io/gpg | sudo gpg --dearmor -o /usr/share/keyrings/valkey.gpg
echo "deb [signed-by=/usr/share/keyrings/valkey.gpg] https://packages.valkey.io/apt stable main" \
  | sudo tee /etc/apt/sources.list.d/valkey.list
sudo apt update && sudo apt install -y valkey

dnf (RHEL/Fedora/Rocky)

sudo dnf install -y https://packages.valkey.io/rpm/valkey-release-latest.rpm
sudo dnf install -y valkey

Docker

# Single instance
docker run -d --name valkey -p 6379:6379 valkey/valkey:latest

# With persistence
docker run -d \
  --name valkey \
  -p 6379:6379 \
  -v valkey-data:/data \
  valkey/valkey:latest valkey-server --save 60 1 --loglevel warning

Build from Source

git clone https://github.com/valkey-io/valkey.git
cd valkey && git checkout 7.2.9
make -j$(nproc)
sudo make install

---

Migrating from Redis to Valkey

Valkey reads Redis RDB snapshot and AOF journal files directly — no conversion required.

Step 1: Flush and Save Redis Data

redis-cli SAVE
sudo cp -r /var/lib/redis /var/lib/redis-backup

Step 2: Stop Redis

sudo systemctl stop redis-server
sudo systemctl disable redis-server

Step 3: Configure Valkey

sudo cp /etc/redis/redis.conf /etc/valkey/valkey.conf
# Point Valkey at the existing data directory
sudo sed -i 's|^dir .*|dir /var/lib/redis|' /etc/valkey/valkey.conf

valkey.conf uses identical syntax to redis.conf. Every directive — bind, requirepass, maxmemory, eviction policies, TLS, RDB, AOF — works unchanged.

Step 4: Update the systemd Unit

sudo systemctl enable valkey-server
sudo systemctl start valkey-server

Step 5: Verify the Migration

valkey-cli PING          # → PONG
valkey-cli INFO server   # shows Valkey version and data loaded
valkey-cli DBSIZE        # confirm key count matches pre-migration

Step 6: Update Application Connection Strings

Change host: redis to host: valkey (or the new IP/hostname). No other code changes are needed — all Redis client libraries connect to Valkey transparently.

---

Configuration Reference

Key valkey.conf settings identical to redis.conf:

Directive	Example	Purpose
bind	bind 127.0.0.1 ::1	Listen addresses
requirepass	requirepass s3cr3t	Password auth
maxmemory	maxmemory 2gb	Memory cap
maxmemory-policy	allkeys-lru	Eviction policy
save	save 900 1	RDB snapshot schedule
appendonly	appendonly yes	Enable AOF
appendfsync	appendfsync everysec	AOF fsync mode
tls-port	tls-port 6380	TLS listener

---

New Valkey Features (Beyond Redis 7.2)

Valkey ships several improvements not present in Redis OSS:

• RDMA transport — Remote Direct Memory Access for ultra-low-latency clusters (Valkey 8.0+).
• Per-slot dict in cluster mode — Each of the 16,384 hash slots gets its own dictionary, reducing lock contention and improving cluster throughput.
• Dual-channel replication — Replicas use a dedicated channel for bulk data transfer and another for live command streaming, reducing full-sync impact on primaries.
• Improved memory efficiency — listpack encoding threshold tuning, reduced per-key overhead vs Redis 7.2.

---

Valkey Cluster

Valkey Cluster uses the same 16,384 hash-slot model as Redis Cluster. Existing cluster tooling works unchanged.

# Create a 6-node cluster (3 primary + 3 replica)
valkey-cli --cluster create \
  192.168.1.1:7000 192.168.1.2:7001 192.168.1.3:7002 \
  192.168.1.4:7003 192.168.1.5:7004 192.168.1.6:7005 \
  --cluster-replicas 1

# Check cluster status
valkey-cli --cluster check 192.168.1.1:7000

# Reshard slots
valkey-cli --cluster reshard 192.168.1.1:7000

# Add a new node
valkey-cli --cluster add-node 192.168.1.7:7006 192.168.1.1:7000

---

Sentinel for High Availability

valkey-sentinel replaces redis-sentinel with identical configuration:

# /etc/valkey/sentinel.conf
sentinel monitor mymaster 192.168.1.1 6379 2
sentinel auth-pass mymaster s3cr3t
sentinel down-after-milliseconds mymaster 5000
sentinel failover-timeout mymaster 60000
sentinel parallel-syncs mymaster 1

valkey-sentinel /etc/valkey/sentinel.conf

---

Docker Compose Production Setup with Sentinel

services:
  valkey-primary:
    image: valkey/valkey:latest
    command: valkey-server --requirepass ${VALKEY_PASSWORD} --appendonly yes
    volumes:
      - valkey-primary-data:/data
    networks: [valkey-net]

  valkey-replica:
    image: valkey/valkey:latest
    command: >
      valkey-server
      --replicaof valkey-primary 6379
      --requirepass ${VALKEY_PASSWORD}
      --masterauth ${VALKEY_PASSWORD}
      --appendonly yes
    volumes:
      - valkey-replica-data:/data
    networks: [valkey-net]
    depends_on: [valkey-primary]

  valkey-sentinel:
    image: valkey/valkey:latest
    command: >
      valkey-sentinel /etc/valkey/sentinel.conf
    configs:
      - source: sentinel-conf
        target: /etc/valkey/sentinel.conf
    networks: [valkey-net]
    depends_on: [valkey-primary, valkey-replica]

volumes:
  valkey-primary-data:
  valkey-replica-data:

networks:
  valkey-net:

configs:
  sentinel-conf:
    content: |
      sentinel monitor mymaster valkey-primary 6379 1
      sentinel auth-pass mymaster ${VALKEY_PASSWORD}
      sentinel down-after-milliseconds mymaster 5000
      sentinel failover-timeout mymaster 30000

---

Client Library Compatibility

Every Redis client works with Valkey by changing the hostname only:

Library	Language	Change Required
redis-py	Python	Redis(host="valkey-host")
ioredis	Node.js	new Redis({ host: "valkey-host" })
Jedis	Java	new JedisPool("valkey-host", 6379)
go-redis	Go	Addr: "valkey-host:6379"
StackExchange.Redis	.NET	"valkey-host:6379"
lettuce	Java	RedisURI.create("valkey://valkey-host")

---

Valkey vs Redis vs Alternatives

Feature	Valkey	Redis OSS	Redis Enterprise	KeyDB	Dragonfly	Garnet
License	BSD 3-Clause	SSPL/RSAL	Proprietary	BSD	BSL 1.1	MIT
Governance	Linux Foundation	Redis Ltd	Redis Ltd	Snap Inc	Dragonfly DB	Microsoft
Redis compat	Full (7.2)	Native	Full	Full	High	High
Cluster	Yes	Yes	Yes	Yes	Yes	Yes
Modules	Community	Stack	Stack + extras	Limited	Limited	Limited
RDMA	Yes (v8+)	No	Partial	No	No	No
Cost	Free	Free	Paid	Free	Free (core)	Free

---

Performance Benchmarking

# Basic benchmark — 100k requests, 50 parallel clients
valkey-benchmark -h 127.0.0.1 -p 6379 -n 100000 -c 50

# Pipeline mode (10 commands per pipeline)
valkey-benchmark -n 1000000 -P 10

# Test only SET/GET
valkey-benchmark -t set,get -n 500000

Valkey matches or slightly exceeds Redis 7.2 throughput on equivalent hardware, with improvements in cluster mode due to per-slot dicts.

---

Monitoring

# Real-time stats
valkey-cli --stat

# Full INFO output sections
valkey-cli INFO all
valkey-cli INFO replication   # replica lag
valkey-cli INFO memory        # used_memory_human, fragmentation ratio
valkey-cli INFO keyspace      # per-db key counts

The community-maintained oliver006/redis_exporter Prometheus exporter works with Valkey unchanged — it detects server info via INFO command. Import the Redis / Valkey Grafana dashboard (ID 763) for instant visibility.

---

Summary

• Valkey is the BSD-licensed, Linux Foundation-governed fork of Redis 7.2 — drop-in compatible.
• Migration is straightforward: stop Redis, point Valkey at the existing data directory, start Valkey.
• All Redis clients connect to Valkey without code changes — only the hostname changes.
• Cluster and Sentinel use identical configuration and tooling to Redis.
• New features in Valkey 8+ (RDMA, per-slot dict, dual-channel replication) improve performance beyond Redis 7.2.
• Modules: community alternatives exist; proprietary Redis Stack modules do not ship with Valkey.

Related Articles

• Docker Compose Multi-Container Applications
• Add and Remove Symbolic Links on Ubuntu
• DIUN Docker Image Update Notifier