📚 课程目录第3章 Python串口库安装

3. Python串口库安装

好，咱们进入实战环节的第一步——把pySerial库装好。

说实话，很多初学者一上来就写代码，结果卡在安装这一步。我见过太多人花了一整天折腾环境，最后发现是pip版本不对。所以这节课，咱们把安装这件事彻底讲透。

3.1 为什么选pySerial？

Python的串口库有好几个，但pySerial是公认的“标准答案”。

跨平台：Windows、Linux、macOS都能跑
纯Python实现：不需要额外编译C库
社区活跃：遇到问题基本都能搜到答案
API设计简洁：几行代码就能打开串口收发数据

我个人习惯用pySerial，因为它稳定。我在项目里用过至少十几个版本，从2.7到3.x，从来没出过兼容性大坑。

3.2 pip安装：最直接的方式

打开你的终端（Windows用cmd或PowerShell，Linux/macOS用bash），敲下面这行命令：

pip install pyserial

就这么简单？嗯，大部分情况是的。但如果你遇到问题，往下看。

小提示： 如果你同时装了Python2和Python3，可能需要用 pip3 install pyserial 来指定给Python3安装。

3.3 版本选择：别盲目追新

pySerial目前最新的稳定版是3.5（截至我写这节课时）。但我不建议你无脑装最新版。

版本	特点	推荐场景
3.4+	支持timeout参数改进，修复了部分Windows下的bug	新项目首选
3.0~3.3	功能稳定，API与3.4基本一致	老项目维护
2.7	兼容Python2，但已停止维护	仅用于遗留系统

我个人建议：新项目直接用3.5。如果你在维护老代码，看看它原来用的是哪个版本，别轻易升级——我曾经因为从3.3升到3.4，结果一个老设备的超时逻辑变了，排查了半天。

想装指定版本？很简单：

pip install pyserial==3.5

3.4 常见安装报错及解决

这部分是重点。我整理了最常遇到的几个坑，每个都是我或我学员踩过的。

报错1：pip不是内部或外部命令

现象： 在cmd里敲pip，提示“不是内部或外部命令”。

原因： Python没加到系统环境变量里。

解决：

重新安装Python，安装时勾选“Add Python to PATH”
或者手动把Python的Scripts目录加到PATH里

注意： 别偷懒。我见过有人每次用pip都跑到Python安装目录去执行，太折腾了。一次配好环境变量，一劳永逸。

报错2：pip install 超时或下载慢

现象： 下载到一半卡住，最后报TimeoutError。

原因： 默认连的是PyPI官方源，在国内访问慢。

解决： 换国内镜像源，比如清华源：

pip install pyserial -i https://pypi.tuna.tsinghua.edu.cn/simple

或者永久换源（我习惯这么干）：

pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

报错3：权限不足（Permission denied）

现象： Linux/macOS下提示没有权限写入site-packages。

原因： 当前用户没有系统Python目录的写权限。

解决：

加sudo：sudo pip install pyserial（不推荐，可能搞乱系统Python）
更好的方式：用虚拟环境

    我的建议： 每个项目都建一个虚拟环境。用 python -m venv myenv 创建，然后激活它再装pySerial。这样既不怕权限问题，也不怕不同项目间的依赖冲突。

报错4：找不到匹配的版本

现象： 提示“Could not find a version that satisfies the requirement”。

原因： 你的Python版本太老或太新，pySerial不支持。

解决： 检查Python版本：python --version。pySerial 3.x 要求Python 3.4以上。如果你还在用Python 2.7，装pySerial 2.7版本。

报错5：编译错误（Windows下少见）

现象： 安装过程中出现一堆C++编译错误。

原因： 极少数情况，可能是pip版本太旧，或者系统缺少VC++运行库。

解决：

升级pip：python -m pip install --upgrade pip
安装Visual C++ Redistributable（微软官网可下）

3.5 验证安装是否成功

装完之后，怎么知道装好了？打开Python交互环境，敲两行代码：

import serial
print(serial.__version__)

如果没报错，并且打印出了版本号（比如3.5），恭喜你，安装成功。

一个小技巧： 我每次装完库，都会先跑一下这个验证。别等到写代码时才发现没装上，那会儿心态容易崩。

3.6 知识体系图：安装流程一览

下面这张图帮你理清整个安装流程和可能遇到的问题：

这张图把安装流程和常见问题串起来了。你照着走一遍，基本不会卡住。

3.7 避坑指南：我踩过的几个坑

最后分享几个真实教训：

我曾经在Windows上同时装了Python3.7和3.9，结果pip install装到了3.7，但代码用3.9跑，死活import不到。后来用 python -m pip install pyserial 指定了解释器，问题解决。
我曾经在Linux服务器上直接sudo pip install，结果搞乱了系统自带的Python库，导致yum都坏了。从那以后，我所有项目都用虚拟环境。
还有一个坑：有学员装完pySerial后，运行代码报错“No module named 'serial'”。检查发现他装的是 serial 库（一个老掉牙的库），不是 pyserial。记住，包名是 pyserial，但import时用 import serial。

好了，安装这块就这么多。把环境搭好，后面写代码才顺手。下一节咱们就开始写第一个串口程序——打开端口、收发数据，真正动起来。

    一句话总结： pip install pyserial，换源用清华，环境用虚拟，验证看版本。记住这四句，安装不迷路。

可可精品资料库