redis-py

Warnings

• gotcha decode_responses defaults to False. All values returned as bytes (b'value') not strings. Silently breaks string comparisons, JSON parsing, and any code expecting str.
  Fix: Always pass decode_responses=True unless you specifically need bytes: Redis(host='localhost', decode_responses=True)
• breaking aioredis separate package is abandoned (last release 2021). 'import aioredis' still installs but is dead. Use 'import redis.asyncio as aioredis' from redis >= 4.2.
  Fix: Replace 'import aioredis' with 'import redis.asyncio as aioredis'. API is compatible.
• gotcha SSL connections require 'rediss://' (double s) URL scheme, not 'redis://'. Using wrong scheme silently connects without TLS or raises ConnectionError.
  Fix: redis.from_url('rediss://host:6380') for TLS. 'redis://' is plaintext.
• gotcha Upstash Redis requires TLS — always use rediss:// with Upstash URLs. Using redis:// with Upstash raises ConnectionError.
  Fix: r = redis.from_url(os.environ['UPSTASH_REDIS_URL'], decode_responses=True) — Upstash provides rediss:// URLs automatically.
• gotcha StrictRedis renamed to Redis in v3. StrictRedis still works as an alias but generates confusion in docs. Use Redis directly.
  Fix: from redis import Redis not StrictRedis
• gotcha Connection pool is shared by default. Do not call r.close() in web request handlers — it closes the pool. Use aclose() in async or let the pool manage connections.
  Fix: Create one Redis client at app startup and reuse it. Only close on app shutdown.
• gotcha ZADD argument order changed in v3. Old: zadd(name, member, score). New: zadd(name, {member: score}). Old order raises TypeError silently or produces wrong results.
  Fix: r.zadd('leaderboard', {'player1': 100.0})

Install

• pip install redis Python (sync + async)
• pip install 'redis[hiredis]' Python (with hiredis parser — faster)

Imports

• Redis (sync)

  import redis
  
  r = redis.Redis(
      host='localhost',
      port=6379,
      db=0,
      decode_responses=True  # returns str not bytes
  )
  r.set('key', 'value')
  print(r.get('key'))  # 'value' not b'value'

  decode_responses defaults to False. Without it get() returns bytes (b'value') not str ('value'). This silently breaks string comparisons throughout your code.
• redis.asyncio (async)

  import redis.asyncio as aioredis
  import asyncio
  
  async def main():
      r = aioredis.Redis(
          host='localhost',
          port=6379,
          decode_responses=True
      )
      await r.set('key', 'value')
      print(await r.get('key'))
      await r.aclose()
  
  asyncio.run(main())

  aioredis separate package is abandoned. Use 'import redis.asyncio as aioredis' from redis >= 4.2. aioredis PyPI package last release 2021.
• from_url

  import redis
  
  # Standard Redis URL
  r = redis.from_url('redis://localhost:6379/0', decode_responses=True)
  
  # Redis with password
  r = redis.from_url('redis://:password@localhost:6379/0')
  
  # SSL/TLS (Upstash, Redis Cloud)
  r = redis.from_url('rediss://user:pass@host:6380/0')

  SSL connections use 'rediss://' (double s) not 'redis://'. from_url also defaults to decode_responses=False.

Quickstart

Minimal redis-py 7.x sync operations with decode_responses.

# pip install redis
import redis

r = redis.Redis(
    host='localhost',
    port=6379,
    db=0,
    decode_responses=True  # str not bytes
)

# Basic operations
r.set('name', 'Alice')
print(r.get('name'))  # 'Alice'

# Expiry
r.setex('session', 3600, 'token123')  # TTL 1 hour

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

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

r.close()