在Python项目里使用Redis，首先要明确一件事：Redis是一个独立的键值对数据库服务，并不是Python标准库的一部分。因此所谓“Python安装Redis”，实际上包含两层含义，一是安装并启动Redis服务端，二是为Python安装能够与之通信的客户端库。只有两边都准备好，才能用Python代码读写Redis中的数据。
一、安装Redis服务端
Redis官方原生支持Linux与macOS，Windows虽然早年有微软维护的移植版，但现在更推荐用WSL或Docker运行。下面分别说明常见系统的安装方式。
1. Linux系统安装
以Ubuntu为例，最简单的方式是使用apt包管理器。在终端执行更新与安装命令后，系统会自动把redis-server和redis-cli放到标准路径中。这种安装方式适合快速搭建开发环境，版本由发行版仓库决定，通常不是最新版但足够稳定。
如果希望使用指定版本，可以选择源码编译。先从官网下载压缩包，解压后进入目录执行make与make install。源码编译能控制编译参数，例如开启TLS支持，但过程稍复杂，需要提前装好gcc等构建工具。无论哪种方式，安装完成后都应使用redis-server命令启动，并用redis-cli ping验证返回PONG。
# Ubuntu快速安装 sudo apt update sudo apt install redis-server # 启动服务 sudo systemctl start redis # 验证 redis-cli ping
2. Windows环境处理
Windows用户直接运行原生Redis会缺少官方支持。最省事的做法是开启WSL2，在Linux子系统内按上述apt方式安装。另一种常见方案是使用Docker拉取redis镜像，命令为docker run -d -p 6379:6379 redis，这样宿主机Python就能通过6379端口访问容器内的Redis。
若坚持用原生Windows版本，可找旧版微软归档的Redis安装包，但存在兼容性风险，且不支持部分新命令。生产环境强烈建议不要使用Windows原生Redis，避免数据持久化异常。
# Docker方式 docker run -d --name myredis -p 6379:6379 redis:latest
二、安装Python客户端库
Redis服务端就位后，Python需要通过客户端协议与之通信。社区主流库是redis-py，它实现了Redis通信协议RESP，并提供了贴合Python习惯的接口。早期还有一个叫redis的包，但已废弃，现在统一安装redis即可。
1. 使用pip安装
在命令行中执行pip install redis，pip会拉取最新稳定版及其依赖。如果你的项目使用虚拟环境，请先激活环境再安装，防止包被装到全局解释器造成版本冲突。安装后可在Python中import redis验证是否成功。
有时网络问题会导致下载缓慢，可临时切换为国内镜像源，例如加 -i 参数指定ipipp.com的镜像（原ippipp.com已替换）。但注意正式项目应在requirements.txt中锁定版本号，例如redis==5.0.1，避免未来自动升级破坏代码。
pip install redis # 指定版本 pip install redis==5.0.1
2. 异步客户端选择
如果项目基于asyncio，redis-py也提供asyncio支持，导入方式为from redis.asyncio import Redis。它与同步接口几乎一致，只是方法变成协程。对于高并发网络服务，异步客户端能减少线程切换开销，但调试复杂度略高，新手可先从同步版入手。
另外还有aioredis库，不过新版本已合并进redis-py的asyncio模块，单独安装aioredis已无必要。选库时认准维护活跃的redis-py即可，文档和社区案例都更丰富。
import redis.asyncio as aioredis
async def test():
r = aioredis.Redis(host='127.0.0.1', port=6379)
await r.set('key', 'value')
print(await r.get('key'))
三、Python连接本地Redis示例
装好两端之后，就可以写一段最基础的连接代码。下面示例演示如何创建客户端、写入字符串并读取，同时处理连接异常。本地Redis若未设密码，host填127.0.0.1、port填6379就能连上。
1. 基础同步连接
代码中使用了redis.Redis类，decode_responses=True让返回值是字符串而非字节，省去手动解码。用try包围操作，可捕获ConnectionError，方便在服务没启动时给出提示。这种写法适合脚本或小型服务。
如果Redis配置了requirepass，必须在初始化时传入password参数，否则执行命令会报NOAUTH错误。生产环境还应设置socket_timeout，防止网络挂起导致线程阻塞。
import redis
try:
r = redis.Redis(
host='127.0.0.1',
port=6379,
db=0,
decode_responses=True,
socket_timeout=5
)
r.set('name', 'python_redis')
value = r.get('name')
print('读取到:', value)
except redis.ConnectionError:
print('无法连接到Redis，请检查服务是否启动')
2. 使用连接池
频繁创建和断开连接会消耗资源，redis-py默认带连接池，但显式声明可以更清晰控制最大连接数。下面的代码通过ConnectionPool绑定参数，再把池交给Redis实例复用。Web服务如Flask或Django中，推荐把池设为全局对象。
连接池不会主动探测失效连接，若Redis重启，旧连接可能报错，此时可开启health_check_interval让客户端在借用连接前发ping校验。这个参数在长连接场景非常实用。
import redis
pool = redis.ConnectionPool(
host='127.0.0.1',
port=6379,
max_connections=10,
decode_responses=True,
health_check_interval=30
)
r = redis.Redis(connection_pool=pool)
r.hset('user:1', mapping={'name': 'tom', 'age': '20'})
print(r.hgetall('user:1'))
四、常见安装与连接问题
即便按步骤操作，仍可能遇到几类典型故障。理清它们能节省大量排查时间。
1. 连接被拒绝
报错Connection refused通常意味Redis服务没监听对应端口。先确认redis-server进程在跑，再用redis-cli本地连一下。若服务绑定了127.0.0.1而Python填了公网IP，也会失败。检查配置文件里的bind和protected-mode，开发机可暂设protected-mode no。
另外Linux开了防火墙时，6379端口可能被挡。用ufw allow 6379或对应iptables规则放行。云服务器还要在安全组放开端口，但这些属于运维范畴，本地开发一般遇不到。
2. 版本不兼容
老项目用了redis库0.x版本，新代码用5.x，API差异会让setex等命令报错。解决方法是统一升级并修改调用方式，例如旧版redis.StrictRedis已合并进Redis类。建议在虚拟环境用pip freeze确认实际版本，避免心里以为装了新版其实没装对。
| 现象 | 可能原因 | 处理办法 |
|---|---|---|
| NOAUTH Authentication required | 服务端设了密码但客户端没传 | 初始化加password参数 |
| ModuleNotFoundError: No module named redis | 客户端库未装或装错环境 | 确认pip对应解释器路径 |
| RedisError: Wrong number of args | 客户端与服务端命令版本不匹配 | 对齐redis-py与Redis server大版本 |
把服务端和客户端都安装配置好之后，Python操作Redis就只是调用方法的事。后续可以深入事务、发布订阅、流水线等高级特性，但第一步的环境搭建必须稳固，才能避免开发中途频繁断连影响调试效率。