Bruce/PythonLearn

Fork 0

Files

T

zhiye.sun bf1f7042a9 feat(数据库): 完善第四阶段SQLAlchemy课程与综合项目

2026-08-20 15:45:21 +08:00

13 KiB

Raw Blame History

附录：Psycopg安装、环境选择与常见问题排查

一、附录用途

本附录集中说明Windows环境下安装Psycopg 3时容易混淆的问题，并整理本课程实际遇到的错误。正文只保留数据库编程主线；安装失败、解释器不一致或原生库异常时，再查阅本附录。

本附录覆盖两种安装方式：

使用pip安装；
使用Conda安装。

无论选择哪一种，都应先创建课程专用环境，不建议把课程依赖继续安装到系统级base环境。

二、先分清Psycopg 2和Psycopg 3

以下名称非常相似，但不是同一个版本：

安装包	Python导入语句	说明
`psycopg`	`import psycopg`	Psycopg 3主体包
`psycopg-binary`	仍然使用`import psycopg`	Psycopg 3预编译二进制实现
`psycopg-c`	仍然使用`import psycopg`	Psycopg 3本地C扩展实现
`psycopg2`	`import psycopg2`	Psycopg 2源码/本地库方案
`psycopg2-binary`	`import psycopg2`	Psycopg 2预编译方案

不存在以下正确导入方式：

import psycopg3
import psycopg_binary
import psycopg2_binary

本课程使用Psycopg 3，因此代码统一写：

import psycopg

如果编辑器只能找到psycopg2，通常表示安装的是Psycopg 2，或者编辑器选用了另一个Python解释器。

三、Psycopg 3的三种底层实现

Psycopg 3主体包会选择一种底层libpq包装实现。libpq是PostgreSQL官方客户端库，负责底层数据库通信。

实现	常见安装方式	特点	额外要求
`python`	`pip install psycopg`	纯Python包装，适合调试和小型任务	系统中必须能找到`libpq`
`c`	`pip install "psycopg[c]"`或Conda的`psycopg-c`	C扩展，性能较好	本地`libpq`；pip源码构建还需要编译工具
`binary`	`pip install "psycopg[binary]"`	预编译并自带客户端库，安装最省事	需要当前Python和平台存在可用二进制包

查看当前实际使用的实现：

python -c "import psycopg, psycopg.pq; print(psycopg.__version__); print(psycopg.pq.__impl__); print(psycopg.pq.version())"

可能输出：

3.3.4
binary
180004

其中：

第一行是Psycopg版本；
第二行是python、c或binary实现；
第三行是实际加载的libpq版本号。

四、安装前先确认当前环境

4.1 查看Conda环境

conda env list

当前激活环境前会显示*。

4.2 查看Python解释器

python -c "import sys; print(sys.executable); print(sys.version)"

如果课程环境名为python-test，路径应类似：

C:\Users\你的用户名\.conda\envs\python-test\python.exe

如果仍然显示：

C:\ProgramData\miniconda3\python.exe

说明当前使用的还是系统级base解释器。

4.3 为什么不推荐系统级base

系统级Miniconda可能安装在：

C:\ProgramData\miniconda3

普通用户通常没有写权限，安装时会出现：

EnvironmentNotWritableError

独立环境还可以避免数据库课程依赖污染其他Python项目，也便于删除和重建。

五、方式一：使用pip安装

5.1 创建并激活Conda环境

可以让Conda只负责环境和Python，再让pip安装Psycopg：

conda create -n python-test python=3.13 pip
conda activate python-test

5.2 推荐安装命令

本地学习优先使用预编译二进制实现：

python -m pip install "psycopg[binary]>=3,<4"

也可以使用本课的依赖文件：

python -m pip install -r requirements.txt

requirements.txt中的：

psycopg[binary]>=3,<4

表示：

安装Psycopg 3；
同时安装binary额外依赖；
版本不低于3且低于4。

5.3 为什么使用`python -m pip`

不要优先直接执行：

pip install ...

直接运行pip.exe时，可能遇到访问被拒绝，或者调用了其他环境中的pip。下面的写法明确表示“使用当前Python解释器对应的pip”：

python -m pip install ...

这能降低“包安装成功，但程序使用另一个Python”的概率。

5.4 pip国内镜像临时用法

如果访问PyPI失败，可以只为当前命令指定镜像：

python -m pip install -i https://pypi.tuna.tsinghua.edu.cn/simple "psycopg[binary]>=3,<4"

临时指定不会永久修改系统或用户配置。

5.5 pip安装后的确认

python -m pip show psycopg psycopg-binary
python -c "import sys, psycopg, psycopg.pq; print(sys.executable); print(psycopg.__version__); print(psycopg.pq.__impl__)"

预期底层实现通常是：

binary

六、方式二：使用Conda安装

6.1 创建独立环境并一次安装

推荐让核心包全部来自conda-forge，减少Python、OpenSSL和libpq混用不同频道的风险：

conda create -n python-db --override-channels -c conda-forge python=3.13 psycopg psycopg-c libpq openssl
conda activate python-db

如果已经创建了python-test：

conda activate python-test
conda install -c conda-forge psycopg psycopg-c libpq

不要在激活python-test后仍然写：

conda install -n base ...

-n base会明确要求安装到base，不会因为当前激活了python-test而自动改用当前环境。

6.2 Conda不能使用pip的`-r`

下面的命令是错误的：

conda install -r requirements.txt

-r requirements.txt是pip的参数，不是Conda的通用安装方式。对应写法是：

python -m pip install -r requirements.txt

使用Conda时则应直接写包名：

conda install -c conda-forge psycopg psycopg-c libpq

6.3 配置清华Conda镜像

访问官方conda-forge失败时，可以把conda-forge映射到清华镜像：

conda config --set show_channel_urls yes
conda config --set custom_channels.conda-forge https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud
conda clean --index-cache

查看最终配置来源：

conda config --show-sources
conda config --show custom_channels

Windows用户级配置通常位于：

C:\Users\你的用户名\.condarc

然后重新安装：

conda activate python-test
conda install -c conda-forge psycopg psycopg-c libpq

6.4 Conda安装后的确认

conda list | Select-String "python|psycopg|libpq|openssl"
python -c "import sys, psycopg, psycopg.pq; print(sys.executable); print(psycopg.__version__); print(psycopg.pq.__impl__); print(psycopg.pq.version())"

使用psycopg-c时，底层实现应为：

七、pip和Conda的区别

对比项	pip	Conda
主要管理对象	Python包	Python包、解释器和原生库
默认软件仓库	PyPI	defaults或conda-forge等频道
环境创建	通常配合`venv`或Conda	原生支持`conda create`
`libpq`、OpenSSL等原生依赖	binary包可自带；否则依赖系统	可以作为Conda包统一安装
安装速度与包可用性	PyPI新版本通常更及时	取决于频道是否已构建对应平台包
依赖解析范围	主要关注Python包	同时解析Python和原生库依赖
本课推荐场景	希望安装简单、使用`binary`实现	希望统一管理Python、C扩展和`libpq`

7.1 pip方案的优势

命令与大多数Python项目的requirements.txt一致；
psycopg[binary]通常安装最直接；
预编译包自带所需客户端库，受本机DLL路径影响较小；
PyPI上的版本通常更新较快。

7.2 Conda方案的优势

可以同时管理Python、psycopg-c、libpq和OpenSSL；
不需要手工准备Visual Studio C++编译环境；
适合已经使用Conda管理数据分析或科学计算环境的项目。

7.3 不建议随意混装

同一个环境中可以混合使用Conda和pip，但顺序和边界必须清楚。推荐：

先用Conda安装Python及能够满足的原生依赖；
再用当前环境的python -m pip安装Conda没有的Python包；
pip安装后不要再让Conda大范围重算并替换同一批核心依赖；
出现原生崩溃时，检查Python、Psycopg、libpq和OpenSSL是否来自相互兼容的来源。

本课程选择一种方案成功后即可，不需要同时安装psycopg-c和psycopg-binary。

八、实际遇到的问题与原因

8.1 `conda install -r requirements.txt`报参数错误

错误原因：把pip参数用于Conda。

正确处理：

python -m pip install -r requirements.txt

或者使用Conda包名安装。

8.2 直接运行`pip.exe`显示`Access is denied`

可能原因包括pip.exe权限、命令解析或环境路径异常。

优先改为：

python -m pip install -r requirements.txt

同时用sys.executable确认当前Python。

8.3 `EnvironmentNotWritableError`

典型信息：

environment location: C:\ProgramData\miniconda3

原因：普通用户没有系统级base环境写权限。

推荐处理：创建用户自己的独立环境，不要修改系统目录权限：

conda create -n python-test python=3.13 pip
conda activate python-test

8.4 激活新环境后仍然安装到base

错误命令：

conda activate python-test
conda install -n base -c conda-forge psycopg

-n base覆盖了当前环境选择。正确写法：

conda install -c conda-forge psycopg

或明确指定：

conda install -n python-test -c conda-forge psycopg

8.5 CondaHTTPError访问`conda-forge`失败

先检查：

conda config --show-sources
conda config --show channels
conda config --show proxy_servers

配置没有错误时，可能是网络、代理或官方源可达性问题。可以使用前面的清华镜像配置后清理索引缓存重试。

8.6 只能导入`psycopg2`

原因通常是安装了psycopg2-binary，而不是Psycopg 3。

确认命令：

python -c "import importlib.util; print(importlib.util.find_spec('psycopg')); print(importlib.util.find_spec('psycopg2'))"
python -m pip show psycopg psycopg-binary psycopg2-binary

本课程需要psycopg能够被找到。

8.7 `no pq wrapper available`

典型信息：

- couldn't import psycopg 'c' implementation
- couldn't import psycopg 'binary' implementation
- couldn't import psycopg 'python' implementation: libpq library not found

含义：

没有psycopg-c；
没有psycopg-binary；
纯Python实现又找不到libpq。

解决方式任选其一：

python -m pip install psycopg-binary

或者通过Conda安装完整本地库：

conda install -c conda-forge psycopg psycopg-c libpq

8.8 PyCharm退出代码`0xC0000005`

0xC0000005是Windows原生访问冲突，不是普通Python异常，try...except无法捕获。它曾发生在psycopg.connect()进入C扩展或客户端DLL后。

排查步骤：

在终端使用同一个解释器运行同一文件；
输出sys.executable确认解释器一致；
输出psycopg.pq.__impl__确认底层实现；
检查环境是否混用了不同频道的Python、psycopg-c、libpq和OpenSSL；
优先重建核心包来源一致的环境；
本地学习也可以改用psycopg-binary降低DLL路径差异。

Conda的Windows原生库通常位于：

C:\Users\你的用户名\.conda\envs\环境名\Library\bin

PyCharm必须选择正确的Conda解释器。必要时检查其运行配置是否能找到该目录中的DLL。

九、编辑器解释器检查

在PyCharm中选择的解释器必须与终端验证成功的解释器一致。例如：

C:\Users\你的用户名\.conda\envs\python-test\python.exe

可以在程序中临时确认：

import sys

print(sys.executable)

如果终端能够导入、PyCharm不能导入，通常不是代码问题，而是编辑器解释器或原生库搜索路径不同。

十、最终安装验收清单

依次执行：

conda env list
python -c "import sys; print(sys.executable); print(sys.version)"
python -c "import psycopg, psycopg.pq; print(psycopg.__version__); print(psycopg.__file__); print(psycopg.pq.__impl__); print(psycopg.pq.version())"

验收标准：

Python路径指向预期的课程环境；
import psycopg成功；
Psycopg主版本为3；
底层实现是预期的binary、c或python；
PyCharm与PowerShell使用同一个解释器；
实际运行第一课连接示例时不出现导入错误或原生崩溃。

安装只解决客户端依赖。数据库地址、端口、防火墙、代理、PostgreSQL监听和账号权限属于连接问题，应与安装问题分开判断。

13 KiB Raw Blame History Unescape Escape