What causes "hiredis package should be >= 3.2.0" in redis/redis-py?

Upgrade hiredis: pip install -U 'hiredis>=3.2.0'.

redis/redis-py · info · ImportError

hiredis package should be >= 3.2.0

Error message

hiredis package should be >= 3.2.0

What it means

Raised at redis/utils.py:26 inside the optional-hiredis import block. The library parses hiredis.__version__ and requires >= 3.2.0; if an older hiredis is installed it does `raise ImportError('hiredis package should be >= 3.2.0')`. This ImportError is caught by the immediately-enclosing `except ImportError` (line 27), which sets HIREDIS_AVAILABLE=False and falls back to the pure-Python RESP parser. Users normally never observe the exception directly; the only observable effect is that the C-accelerated hiredis parser is silently disabled.

Source

Thrown at redis/utils.py:26

from functools import wraps
from typing import TYPE_CHECKING, Any, Dict, List, Mapping, Optional, TypeVar, Union

from redis.exceptions import DataError
from redis.typing import AbsExpiryT, EncodableT, ExpiryT

if TYPE_CHECKING:
    from redis.client import Redis

try:
    import hiredis  # noqa

    # Only support Hiredis >= 3.0:
    hiredis_version = hiredis.__version__.split(".")
    HIREDIS_AVAILABLE = int(hiredis_version[0]) > 3 or (
        int(hiredis_version[0]) == 3 and int(hiredis_version[1]) >= 2
    )
    if not HIREDIS_AVAILABLE:
        raise ImportError("hiredis package should be >= 3.2.0")
except ImportError:
    HIREDIS_AVAILABLE = False

try:
    import ssl  # noqa

    SSL_AVAILABLE = True
except ImportError:
    SSL_AVAILABLE = False

try:
    import cryptography  # noqa

    CRYPTOGRAPHY_AVAILABLE = True
except ImportError:
    CRYPTOGRAPHY_AVAILABLE = False

from importlib import metadata

View on GitHub (pinned to da03cdc7e8)

Solutions

Upgrade hiredis: pip install -U 'hiredis>=3.2.0'.
If you cannot upgrade, uninstall hiredis (pip uninstall hiredis) so the import simply fails into HIREDIS_AVAILABLE=False without the version warning.
Run pip check to detect dependency conflicts capping hiredis.
Pin hiredis>=3.2.0 in requirements.txt / pyproject.toml.

Example fix

# before (requirements.txt)
hiredis==2.3.0
# after
hiredis>=3.2.0

Defensive patterns

Strategy: validation

Validate before calling

import hiredis

def hiredis_version_ok() -> bool:
    parts = hiredis.__version__.split('.')
    return int(parts[0]) > 3 or (int(parts[0]) == 3 and int(parts[1]) >= 2)

# At app startup
try:
    import hiredis
    if not hiredis_version_ok():
        raise RuntimeError(f'hiredis {hiredis.__version__} is too old; upgrade to >=3.2.0')
except ImportError:
    pass  # pure-Python parser will be used

Prevention

Pin hiredis>=3.2.0 alongside redis in requirements.txt / pyproject.toml.
Run `pip check` in CI to catch version conflicts.
Recreate virtualenvs after upgrading redis-py to avoid stale hiredis wheels.
Monitor logs/telemetry for the hiredis-disabled state if parser throughput matters.

When it happens

Trigger: Importing redis (or any module that imports redis.utils) in an environment where an older hiredis (< 3.2.0, e.g. 2.x, 3.0.x, 3.1.x) is installed. The version check at lines 22-24 evaluates HIREDIS_AVAILABLE=False and the inner raise triggers the except branch.

Common situations: Stale virtualenv pinning hiredis<3.2; OS distribution packages shipping older hiredis; transitive dependency caps from another library; CI image with an old hiredis wheel; recent redis-py upgrade without upgrading hiredis.

Related errors

AI-assisted analysis of redis/redis-py@da03cdc7e8 (2026-08-04). Data as JSON: /data/errors/73ffdb183de73c6c.json. Report an issue: GitHub.