HOWTO: Migration from Redis to Valkey

đź“Š Plotly Python
1

With Redis moving to RSAL + SSPL licensing, many downstream projects are scrambling to stay fully open‑source. Several major Linux distributions are already planning to drop Redis in favor of Valkey, the community fork that retains the original BSD‑3‑Clause license (Arch Linux and Alpine are leading the charge; Fedora and openSUSE will follow soon).

Because Valkey (valkey-py on PyPI) is a true drop‑in replacement for Redis (redis-py on PyPI) – same client API, including redis.asyncio – you can shim your own project so that:

  • pip thinks “redis” is already installed, and
  • every import redis ... transparently loads Valkey

The best part is that this happens without editing a single line of third‑party code.

1. Create a directory named redis_alias in the root of your project.

2. Create ./redis_alias/pyproject.toml with the following contents:

     # redis_alias/pyproject.toml
     [build-system]
     requires = ["setuptools>=64", "wheel"]
     build-backend = "setuptools.build_meta"
     
     [project]
     name = "redis"                   # Satisfies “redis>=…” pins
     version = "99.0.0"               # Absurdly high to satisfy any spec
     dependencies = ["valkey>=6.0"]   # Pulls in the real client
     description = "Stub that replaces Redis with Valkey"
     
     [tool.setuptools]
     py-modules = ["sitecustomize"]   # sitecustomize will make every "import redis..." resolve to valkey

3. Create ./redis_alias/sitecustomize.py with the following contents:

    # redis_alias/sitecustomize.py
    import importlib, sys

    v = importlib.import_module("valkey")      # pip install valkey‑py
    sys.modules["redis"] = v                   # sync API
    sys.modules["redis.asyncio"] = v.asyncio   # async API (optional)

4. Install the stub into your virtual environment

With your virtual environment activated, run from the project root pip install ./redis_alias

How it works

The [project] section of the pyproject.toml causes a stub package named redis with version 99.0.0 to be installed into the virtual environment. All this stub package does is install valkey, but to pip it will look like redis is installed. This satisfies libraries that pin redis in their install_requires.

The [tool.setuptools] section installs the sitecustomize.py module into the virtual environment’s site-packages directory.

sitecustomize.py is loaded by Python’s site machinery and performs the actual aliasing: it imports valkey and loads it into sys.modules. After this is done, all downstream import redis calls will end up loading valkey.

Uninstalling

To undo all changes – uninstall the stub package and the sitecustomize module – simply run pip uninstall redis. At this point you can install the real redis with pip install redis.