M1芯片Mac运行pgcli报错求助：无可用pq wrapper

问题场景 #

在M1芯片的Mac上执行以下操作后遇到问题：

1. 通过Docker启动Postgres 13容器，命令：

docker run -it \
  -e POSTGRES_USER="root" \
  -e POSTGRES_PASSWORD="root" \
  -e POSTGRES_DB="ny_taxi" \
  -v $(pwd)/ny_taxi_postgres_data:/var/lib/postgresql/pg_data \
  -p 5001:5002 \
  postgres:13

2. 执行pip3 install pgcli安装pgcli，运行pgcli时出现如下报错：

Traceback (most recent call last):
  File "/opt/homebrew/bin/pgcli", line 5, in <module>
    from pgcli.main import cli
  File "/opt/homebrew/lib/python3.10/site-packages/pgcli/main.py", line 2, in <module>
    from pgspecial.namedqueries import NamedQueries
  File "/opt/homebrew/lib/python3.10/site-packages/pgspecial/__init__.py", line 13, in <module>
    from . import iocommands
  File "/opt/homebrew/lib/python3.10/site-packages/pgspecial/iocommands.py", line 9, in <module>
    import psycopg
  File "/opt/homebrew/lib/python3.10/site-packages/psycopg/__init__.py", line 9, in <module>
    from . import pq  # noqa: F401 import early to stabilize side effects
  File "/opt/homebrew/lib/python3.10/site-packages/psycopg/pq/__init__.py", line 114, in <module>
    import_from_libpq()
  File "/opt/homebrew/lib/python3.10/site-packages/psycopg/pq/__init__.py", line 106, in import_from_libpq
    raise ImportError(
ImportError: no pq wrapper available.
Attempts made:
- couldn't import psycopg 'c' implementation: No module named 'psycopg_c'
- couldn't import psycopg 'binary' implementation: No module named 'psycopg_binary'
- couldn't import psycopg 'python' implementation: libpq library not found

期望运行pgcli后出现密码提示，但无法正常启动。

解决方案 #

报错核心是缺少libpq库，且psycopg的不同实现均无法加载，针对M1 Mac的ARM架构，按以下步骤处理：

• 安装libpq依赖
  用Homebrew安装PostgreSQL的libpq库：

brew install libpq

• 配置环境变量识别libpq
  将libpq的bin目录添加到系统环境变量，确保系统能找到相关工具：

echo 'export PATH="/opt/homebrew/opt/libpq/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

若使用bash，替换.zshrc为.bash_profile或.bashrc。

• 重新安装适配ARM架构的psycopg版本
  卸载现有psycopg相关包，安装预编译的二进制版本：

pip3 uninstall -y psycopg psycopg2
pip3 install psycopg-binary

• 显式指定连接参数启动pgcli
  直接运行pgcli会使用默认用户尝试连接，建议显式指定Docker容器的连接参数：

pgcli -h localhost -p 5001 -u root -d ny_taxi

输入密码root即可完成连接。

额外注意：Docker命令中端口映射为5001:5002，但Postgres默认端口为5432，若未修改容器内Postgres的监听端口，建议将映射改为5001:5432，避免后续连接时因端口不匹配失败。

内容的提问来源于stack exchange，提问作者Napatsakorn Pianchana