Guide · Open source
How to use redis-py: install and run Redis commands in Python
Updated · written with AI from the project's own documentation and checked against our catalogue data
redis-py is the Python interface to the Redis key-value store, and it is maintained by Redis. This guide is for Python developers who need to read and write data in a Redis server. By the end, you will be able to install the library, connect to a local Redis server, store and read values, batch commands with a pipeline, and subscribe to a Pub/Sub channel.
redis-pyredis/redis-py · ★ 13.7k · MIT Install options & downloads Quick start
- 1Start a Redis server. Run a Redis server, for example with the Docker command in the README.
- 2Install redis-py. Run pip install redis, or pip install "redis[hiredis]" for the faster parser.
- 3Create a client. Import redis and create redis.Redis with your host, port and database number.
- 4Store and read a value. Call set() and get() on the client to write and read a key.
- 5Batch commands. Create a pipeline with r.pipeline(), add commands, then call execute().
- 6Listen on channels. Call r.pubsub(), subscribe to channels, and read messages with get_message().
What you need before you install redis-py
You need Python and a running Redis server. The README does not run Redis for you, so you must start a server first. It shows Docker as one way to do this.
- Python: the README notes that supported Python versions change by release, so check the Note lines in the README before choosing a version.
- A running Redis server, for example via Docker.
docker run -p 6379:6379 -it redis:latestInstall redis-py with pip
Install the library with pip. For faster response parsing, the README suggests installing with hiredis support, which provides a compiled response parser. It says this requires zero code changes in most cases.
- Basic install.
- Install with the faster hiredis parser.
pip install redis
pip install "redis[hiredis]"Connect to Redis and run your first commands
Import redis and create a client with the host, port and database number. The README example connects to localhost on port 6379, sets the key foo, and reads it back. By default, responses come back as bytes, so the value prints as b'bar'.
To receive decoded strings instead, set decode_responses=True. The README points to its examples page for this and other connection options.
import redis
r = redis.Redis(host='localhost', port=6379, db=0)
r.set('foo', 'bar')
r.get('foo')Use connection pools and async or cluster clients
By default, each Redis instance gets its own connection pool. You can define your own pool and pass it to the client. The README also mentions async connections, Cluster connections and async Cluster connections, and links to documentation for each.
- Async connections: see the asyncio examples in the docs.
- Cluster connections: see the cluster client section in the docs.
- Async Cluster connections: see the async cluster client section in the docs.
pool = redis.ConnectionPool(host='localhost', port=6379, db=0)
r = redis.Redis(connection_pool=pool)Batch commands with pipelines
A pipeline batches Redis commands to reduce round-trip calls, and returns their results as a list. By default, the pipeline is wrapped in MULTI and EXEC when executed. You can turn this off by passing transaction=False.
pipe = r.pipeline()
pipe.set('foo', 5)
pipe.set('bar', 18.5)
pipe.set('blee', "hello world!")
pipe.execute()Subscribe to Pub/Sub channels
Pub/Sub lets your program receive messages sent on channels. Call pubsub() on the client to get a PubSub object, then subscribe to one or more channels and read messages. The README notes that a PubSub connection cannot run non-pubsub commands, and that only PUBLISH can be called from the Redis client itself.
r = redis.Redis(...)
p = r.pubsub()
p.subscribe('my-first-channel', 'my-second-channel', ...)
p.get_message()What people use it for
- Storing and reading key-value data from a Python program.
- Building caching or session storage on a Redis server, as suggested by the target audience.
- Batching several Redis commands into one round trip with a pipeline.
- Receiving messages on Redis channels with Pub/Sub.
- Connecting Python code to Redis Cluster or using async code with Redis.
Frequently asked questions
Is redis-py free to use?
Yes. The repository is licensed under MIT, as shown in its license badge and the project summary. Check the LICENSE file in the repository for the full terms.
How do I install redis-py?
Run pip install redis in your terminal. For faster response parsing, run pip install "redis[hiredis]" instead.
Do I need a Redis server to use redis-py?
Yes. redis-py is a client library that connects to a Redis server. The README shows how to start one with Docker using docker run -p 6379:6379 -it redis:latest.
Why do my Redis values come back as bytes?
By default, all responses are returned as bytes in Python. Set decode_responses=True when creating the client to receive decoded strings.
Which Python versions does redis-py support?
It depends on the release. The README notes that support for older Python versions ends in later releases, so check the Note lines in the README for the version that matches your Python.
Is redis-py an alternative to redis-om-python or aioredis?
redis-py is the low-level, official Redis client. The README points to redis-om-python if you want a high-level object-mapping library. Other comparable projects listed are aioredis and valkey-py.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Use redis-py if you write Python code that needs to read and write a Redis server, and you want the official Redis-maintained client. If you need object mapping, the README points you to redis-om-python instead, and if you are not writing code, this library is not an app you can run directly.
Install options & downloads