前阵子做一个小工具要用HC05蓝牙模块和电脑串口通信结果在PyCharm里第一步就栽在了装pyserial上。这个库看着简单网上一搜教程满天飞可真照着操作下来各种报错照样能把人绕晕“pip不是内部或外部命令”“Permission denied”“No module named serial”……我索性把整个安装过程重新捋了一遍把踩过的坑和验证过的方法都记录下来写成了这篇东西。pyserial是Python操作串口的事实标准库包名叫pyserial可代码里导入时却写import serial。一个名字搞两套很多人第一次就懵了。这篇文章适合刚学Python串口通信、准备接HC05蓝牙模块、L298N电机驱动这些硬件的外包开发者也适合在PyCharm里装第三方包经常莫名其妙报错的人。看完你不仅能装好pyserial还能学会一套排查Python包安装问题的通用思路。1. 先把pyserial这件事看明白再动手1.1 pyserial到底是个啥包名和模块名为何不一样pyserial是一个第三方Python库专门用来和电脑上的串口Windows里叫COM口Linux里叫tty设备交流数据。几乎所有用Python做嵌入式开发、硬件调试的人都绕不开它。它的功能说白了就是三件事打开串口、往串口发数据、从串口读数据。但这里有个特别容易让人犯迷糊的点PyPI上的安装包名字是pyserial写代码时导入的模块名却是serial。所以你看网上的教程安装命令是pip install pyserial可代码第一行永远都是import serial。如果你哪天看到有文章写“import pyserial”那基本可以断定作者没真正跑过代码。还有一些老资料会提到serial这个包名其实PyPI上也有一个叫serial的第三方包但它和pyserial完全是两回事千万别搞混否则你装了一堆依赖代码照样跑不起来。pyserial本身的优点是跨平台Windows、Linux、macOS都能用而且同时支持Python 2和Python 3依赖极少整个安装包也就几百KB。按道理说这种轻量级库不应该装出问题但实际操作里大家还是经常翻车原因绝大多数都不在pyserial本身而是环境配置有问题。所以我一直觉得解决安装报错的第一步不是反复重装库而是先把自己的Python环境看清楚。1.2 安装前必须确认的三样东西无论你打算用哪种方法安装动手前都建议先确认下面三件事能省掉后面一大堆排查时间。第一当前项目用的Python解释器是谁。打开PyCharm看右下角状态栏那里会显示当前解释器的名字和路径。如果你有多个Python版本比如系统里同时装了Python 3.9、3.11还装了Anaconda那就必须搞清楚PyCharm现在用的到底是哪一个。因为pip install装到的是当前终端激活的那个Python不一定就是你代码运行用的那个Python。第二项目有没有创建虚拟环境。PyCharm新建项目时默认会创建venv虚拟环境如果你一路点“Next”没注意项目就会带着一个venv目录。打开PyCharm底部的Terminal如果命令行前面有(venv)几个字说明终端已经自动激活了虚拟环境此时pip安装的所有包都会进入这个虚拟环境不会污染系统Python。这是最理想的状态。如果命令行前面啥都没有说明终端使用的是全局Python包会装到系统目录。第三pip版本和网络源是否正常。执行python -m pip --version可以查看pip版本和它对应的Python路径如果这条命令能正常打印出版本号说明Python和pip基本没问题。至于网络源国内默认源是pypi.org经常抽风下文会细说怎么换镜像源。1.3 为什么明明是“装库”却经常要查环境很多人在网上搜“pycharm安装教程”跟着做了半天最后还是装不上pyserial就开始怀疑是不是PyCharm这个软件有问题。其实真不怪PyCharmPyCharm只是一个编辑器加项目管理工具它本身不负责管理Python包包管理是pip和Python解释器的事。问题往往出在解释器配置不一致上。举个例子你在PyCharm的Settings里看到Python Interpreter指向A环境的Python但打开Terminal时命令行实际用的却是B环境的Python。这俩如果不一致你就可能遇到“图形界面里看包已经装上了代码一运行照样No module found”的诡异现象。另外PyCharm新版界面和旧版不一样2020年之后的版本Settings入口和Package对话框都改过网上搜到的教程如果截图很老对不上号也很正常不影响本质思路。所以在进入安装环节之前我建议大家先把“当前解释器是谁”“有没有虚拟环境”“pip归谁管”这三个问题搞清楚。这三句话搞明白后面无论装什么包成功率都会高一大截。2. PyCharm中安装pyserial的3种高效方法2.1 方法一用PyCharm的Terminal跑pip命令这是我最推荐的方式也适合绝大多数场景因为你能看到完整日志遇到错误可以直接看到原因。操作步骤很简单打开PyCharm在当前项目里点击底部Tool Windows里的Terminal或者通过菜单View切换出来。确认命令行前面有(venv)前缀。如果没有用cd命令进入项目根目录然后手动激活虚拟环境。Windows下执行venv\Scripts\activatemacOS或Linux下执行source venv/bin/activate。执行安装命令pip install pyserial如果网络很慢或者反复超时就加上国内镜像源pip install pyserial -i https://pypi.tuna.tsinghua.edu.cn/simple安装成功后最后几行会显示Successfully installed pyserial-3.5看到这个就说明已经装好了。这里我想多说一句关于python -m pip install和pip install的区别。当系统里存在多个Python版本时直接用pip这个命令调用的可能是你最先装的那个Python的pip这不一定是你需要的。而python -m pip install pyserial会强制使用当前命令行里Python对应的pip更稳妥。在PyCharm的Terminal里只要虚拟环境激活正确python和pip就都是虚拟环境里的用哪个都行但出了PyCharm自己开终端的时候这个细节特别重要。另外如果你发现pip版本太老可以先升级pip再装库python -m pip install --upgrade pip老版本pip在解析一些新包的元数据时会出问题偶尔会出现明明包存在但它说找不到版本的情况。2.2 方法二在Python Interpreter里图形化安装不习惯命令行的朋友可以用PyCharm自带的图形化安装界面这种方式的好处是能直观看到当前解释器路径不容易装错环境。具体步骤打开PyCharm点击菜单File下拉里选择SettingsmacOS上是在PyCharm菜单里找Preferences。左侧栏展开Project:你的项目名找到Python Interpreter。右侧顶部会显示当前解释器的完整路径先确认这里选中的是你项目实际使用的解释器。点击路径右侧的号按钮弹出Available Packages搜索窗口。在搜索框输入pyserial下方列表过滤出这个包。点击左下角Install Package按钮。安装过程中左下角有进度条如果一直停在进度条通常是网络问题等一会儿或者换成国内源。换源的方法是点击左下角Manage Repositories先把默认的官方源地址解绑再添加清华源或阿里源保存后重新搜索安装即可。这个方法对新手特别友好因为它把解释器路径明明白白写在了界面上你能确认包到底装到了哪个环境里。不过它的缺点是一旦安装失败提示往往比较笼统只弹出一个Install failed具体原因还得去日志里翻。所以如果图形化安装失败我还是建议回到Terminal里执行pip install看看完整报错。2.3 方法三离线whl文件安装如果你所在的电脑完全不联网或者处于内网办公环境那离线安装就是救命方案。提前在一台联网电脑上把whl文件下载好拷贝过去就能装。步骤在一台能联网的电脑上打开浏览器访问pypi.org搜索pyserial找到Files列表下载这个文件pyserial-3.5-py2.py3-none-any.whl。把这个whl文件用U盘或者内部传输工具拷贝到目标电脑。在PyCharm的Terminal里执行本地安装命令pip install D:\downloads\pyserial-3.5-py2.py3-none-any.whlLinux或macOS就把路径换成对应的绝对路径或相对路径。这里有个通用知识点值得记一下whl文件名里的py2.py3-none-any是平台标签意思是对Python 2和Python 3都兼容且不依赖特定操作系统任何平台都能装所以pyserial的whl文件去哪里都通用。但以后如果你要离线安装pandas、numpy这类带C扩展的库文件名里会有类似cp39-cp39-win_amd64这样的标记必须和目标机器的Python版本、操作系统版本严格匹配不能随手拿一个就能装。pyserial是纯Python包才敢这么随便。离线安装完同样会提示Successfully installed之后想卸载也很简单pip uninstall pyserial即可。2.4 三种方法怎么选一张表看懂安装方式适用场景优点缺点Terminal pip日常开发网络正常日志清晰容易排查问题推荐首选需要稍微懂一点命令行Python Interpreter图形界面新手或者想确认解释器路径界面直观不容易装错环境失败提示笼统排错能力弱离线whl断网、内网隔离环境不受网络影响稳定可控需要提前下载文件复杂包还要匹配平台我个人建议是网络条件允许就优先用第一种方法因为你以后装任何包都会遇到报错熟悉命令行pip的报错逻辑对排查问题非常有帮助。图形化安装适合第一次接触PyCharm的新手先把东西装成功建立起信心再说。离线安装属于特殊场景掌握思路就好。3. 常见报错与排查方法3.1 pip命令提示“不是内部或外部命令”这是Windows用户最容易撞上的报错完整提示是“pip不是内部或外部命令也不是可运行的程序或批处理文件”。这个报错的本质是系统在PATH环境变量里找不到pip也就是说Python可能没装好或者装的时候没勾选Add Python to PATH。最简单的规避方法就是在PyCharm的Terminal里操作不要自己另外开一个cmd窗口。因为PyCharm已经配置好了解释器Terminal会继承这个环境一般不会出现找不到pip的情况。如果PyCharm的Terminal里也提示找不到pip那要检查Python解释器本身是否正常。更稳妥的命令是python -m pip install pyserial这条命令会先去找python再让python自己去找pip模块。如果python本身能运行pip一般是没问题的。如果连python都不认识那就得重新安装Python安装时务必勾选Add Python to PATH装完再重启PyCharm。还有一种情况提示的不是pip找不到而是pip后面报一堆traceback说No module named pip。这大概率是Python环境被弄坏了或者用的是某些精简版Python。遇到这种情况可以试一下python -m ensurepip --upgrade把pip重新安装回来。3.2 网络错误、超时和“No matching distribution”换源解决这种报错的长相五花八门常见的有Retrying (Retry(total4, connectNone, readNone, redirectNone, statusNone))...Could not find a version that satisfies the requirement pyserial (from versions: none)ERROR: No matching distribution found for pyserial前两种多半是网络或者源的问题最后一种除了网络问题也可能是pip版本太旧。很多人一看到“No matching distribution”就开始怀疑是不是包名错了其实包名没错就是下载通道不顺畅。解决办法是换国内镜像源。一次性命令pip install pyserial -i https://pypi.tuna.tsinghua.edu.cn/simple如果想永久生效以后懒得每次加参数可以在用户目录下创建一个pip配置文件。Windows用户在C:\Users\你的用户名\AppData\Roaming\pip下创建pip.ini或者直接在用户目录下新建pip文件夹再建pip.iniLinux和macOS用户在~/.pip或者~/.config/pip下创建pip.conf。文件内容如下[global] index-url https://pypi.tuna.tsinghua.edu.cn/simple trusted-host pypi.tuna.tsinghua.edu.cn保存后再执行pip install pyserial之后的所有pip安装都会走清华源。注意trusted-host这行不能省否则有些网络环境下会报SSL证书问题。另外如果确认网络没问题但就是提示找不到版本先把pip升级到最新版再试。老版本pip对某些新包的元数据解析会有问题升级方法上文已经写过。3.3 PermissionError权限不足别一味给管理员权限这类报错也很常见尤其在macOS或Linux上提示通常长这样Could not install packages due to an EnvironmentError: [Errno 13] Permission denied: /usr/local/lib/python3.11/site-packages/...本质上是当前用户没有权限往系统级Python目录里写入文件。很多人遇到这个第一反应是加sudo或者以管理员身份运行其实这是最不推荐的做法。因为系统Python环境是很多工具共享的你不小心污染了后面其他项目全都会遭殃。正确的做法是给项目创建虚拟环境然后在虚拟环境里安装这就不会存在权限问题。PyCharm项目的venv目录就是干这个用的。如果你实在不想建虚拟环境又只想给当前用户安装可以执行pip install --user pyserial这个命令会把包安装到当前用户目录下避免写系统目录。但“user安装”会增加环境复杂度不太建议长期依赖。顺便说一句Windows下如果提示Permission denied可以右键PyCharm图标选择“以管理员身份运行”来临时解决但这同样是治标不治本的办法。真正稳妥的还是用虚拟环境隔离干净。3.4 明明安装成功import serial还是No module found这是所有人最崩溃的情况屏幕明明显示Successfully installed pyserial代码里import serial却报ModuleNotFoundError: No module named serial。排查顺序我建议按下面几步来第一步确认当前终端环境。在PyCharm的Terminal里看命令行有没有(venv)前缀。如果没有说明pip把包装到了全局环境而PyCharm运行代码时用的可能是虚拟环境两边对不上。解决办法是激活虚拟环境后重新安装。第二步查看Python解释器路径。在Terminal里执行python -c import sys; print(sys.executable)看输出的路径是否和PyCharm右下角显示的解释器路径一致。如果不一致说明终端和PyCharm用的根本不是同一个Python这需要你在Settings里把解释器路径统一起来。第三步直接测试导入。执行python -c import serial; print(serial.__version__)如果这一步成功说明装到哪里都没问题那问题就出在PyCharm的索引或者运行配置上试试File菜单里的Invalidate Caches / Restart把缓存清掉再重开项目。还有一个不起眼但真实存在的坑你装的是pyserial结果代码里import的也是serial但系统里恰好有个不相关的serial包抢占了模块名。用pip show serial和pip show pyserial分别查看如果发现serial不是pyserial提供的那就卸载掉不相关的那个。我自己就遇到过这种情况装的包和模块名刚好撞车排查了半天。3.5 新系统上的PEP 668和conda环境报错这两年随着Linux发行版更新不少用户会遇到一个看起来莫名其妙的报错error: externally-managed-environment This environment is externally managed这是PEP 668引入的保护机制目的很朴素某些Linux发行版对Python系统环境进行了严格管理不允许pip直接往里装第三方包避免把系统包管理器维护的Python弄乱。如果你确认不需要动系统环境正解还是创建虚拟环境在venv里装。如果你确实无所谓想强行装可以用pip install --break-system-packages pyserial但这属于破坏性操作风险自负我一般不推荐。另外用Anaconda作为解释器的用户也要留心。你在PyCharm里打开了Terminal默认可能激活的是conda的base环境pip install会装到base里。如果你的项目用的是另一个conda环境就得先执行conda activate环境名再执行pip install pyserial。这类问题看终端提示符就能判断命令行前面出现的是(base)还是(venv)一眼就能看懂。为了方便大家对照排查我做了一个速查表报错信息最常见原因推荐解法pip不是内部或外部命令Python未加入PATH或未安装用python -m pip重装PythonRetrying / timeout官方源网络不稳定换清华、阿里等镜像源Could not find a version网络或pip版本太旧换源先升级pipPermissionError: [Errno 13]无权限写系统目录创建venv虚拟环境ModuleNotFoundError解释器或环境不一致统一解释器路径externally-managed-environment新版Linux系统保护用虚拟环境No module named pipPython环境损坏python -m ensurepip4. 装好后的验收和实际联调经验4.1 三步快速验证版本号、解释器路径、导入测试装完pyserial先别急着写一大段业务代码用三步确认环境没问题再往下走。第一步在PyCharm的Terminal里执行python -c import serial; print(serial.__version__)正常会输出3.5之类的版本号。如果没报错说明模块导入没问题。第二步执行python -c import sys; print(sys.executable)把输出路径和PyCharm右下角的解释器路径对一下确认代码运行用的就是刚装包的那个环境。这两条命令加起来用不了十秒钟但能避免绝大多数“装完还是跑不了”的尴尬。第三步在PyCharm的Python Console里执行import serial如果也没报错那环境基本就稳了。之后再去写连接硬件的代码心里才有底。4.2 用pyserial列出电脑上所有可用串口写串口程序的第一步通常不是直接打开某个端口而是先看看电脑有哪些串口可用。pyserial自带的list_ports工具就能做这件事代码非常简单import serial.tools.list_ports ports serial.tools.list_ports.comports() for port in ports: print(port.device, port.description)这段代码在Windows上会输出类似COM3 USB-SERIAL CH340这样的信息在Linux上会输出/dev/ttyUSB0之类的路径。强烈建议把这段逻辑封装成一个小函数每次启动程序时先枚举一遍串口再把结果打印给用户选择。很多嵌入式调试工具都是这么设计的避免用户手动填端口号填错。如果你插上了USB转TTL模块但这段代码根本看不到新端口那基本可以断定是驱动问题比如CH340芯片的驱动没装好或者线材本身有问题。这时候Python代码再对也白搭得先把系统层面的设备识别搞定。4.3 接HC05蓝牙等硬件时连接不上的四个原因装好pyserial、也看到了串口不代表就能立刻和HC05蓝牙模块正常通信。网上搜“hc05蓝牙模块连接不上”能搜出一堆求助帖结合我的经验最常见的其实是这四个原因。第一个是USB转TTL驱动问题。HC05模块自己不带USB接口必须通过USB转TTL小板连接电脑小板上的主控芯片通常是CH340或者CP2102。如果Windows设备管理器里根本看不到COM口或者显示黄色感叹号那就先装对应芯片的驱动再回来讨论Python程序。第二个是COM口号认错。系统分配的COM号可能会因为插拔顺序发生变化比如上一次是COM3下一次变成COM5。不要图省事把COM3硬编码在代码里用上文说的list_ports枚举设备才是正经做法。第三个是波特率不匹配。HC05模块有命令响应模式和透传模式不同模式下默认波特率不一样常见的有9600、38400、115200。pyserial打开串口时设置的波特率必须和蓝牙模块一致否则你往串口发出一堆数据对面收不到或者收到的全是乱码。这种问题光看代码是看不出来的得先确认模块那边的参数。第四个是TX和RX接反或者模块供电不足。串口通信的接线原则是交叉相连设备的TX接USB转TTL的RX设备的RX接USB转TTL的TX。第一次接硬件的人特别容易把这两根线按“同名相连”来接然后发现数据死活不通。电源方面有些HC05模块需要3.3V或5V供电电流不够时会表现为搜索不到蓝牙或者连接后频繁断开。pyserial打开串口的标准代码是import serial try: ser serial.Serial(COM3, 9600, timeout1) print(打开串口成功, ser.name) except serial.SerialException as e: print(打开串口失败, e)注意timeout参数一定要写不然执行ser.read()时如果对端一直不发数据代码就会一直卡在阻塞状态看起来像程序死机。4.4 和L298N电机驱动、ESP32等设备联调的代码思路很多人装pyserial之后第一个项目就是控制小车用L298N电机驱动模块接电机再用单片机接收电脑指令。在这种场景里Python端一般不是直接操作L298N而是通过pyserial往下位机比如Arduino或STM32发指令由下位机解析后控制电机。往串口发数据的代码很简单ser.write(bforward\n)注意write方法接收的是字节类型不是普通字符串。如果你手头是字符串需要先编码data forward ser.write(data.encode(utf-8))读取数据时readline可以按行读取适合下位机按行返回状态信息的场景line ser.readline() print(line.decode(utf-8, errorsignore))如果收到的数据是乱码除了前面说的波特率问题还要检查通信双方的串口参数数据位、停止位、校验位是否一致。pyserial默认是8位数据位、1位停止位、无校验这个参数和大多数单片机默认配置一致但如果下位机改了配置Python这边也要跟着改。至于ESP32这类板子很多人会顺手扩展以太网功能比如LAN8720模块。这种以太网扩展严格来说已经不走串口通信了而是走SPI或者RMII接口和pyserial关系不大。但你在串口调试阶段还是需要pyserial从ESP32的日志串口读取打印信息所以把它装好、理解串口基本用法依然有价值。4.5 几个容易看懵的pyserial接口细节最后补充几个我实际使用中经常见人搞混的接口细节省得你们踩同样的坑。第一程序的串口对象用完一定要关闭ser.close()程序退出时不会自动释放串口资源如果你反复运行调试就会遇到serial.SerialException打开失败原因是串口被上个进程占用尤其是Windows上特别明显。第二in_waiting属性可以帮你判断缓冲区里有没有数据if ser.in_waiting 0: data ser.read(ser.in_waiting)这个比直接sleep然后read更高效能减少CPU空转。第三flush和reset_input_buffer这类方法在实际联调时很有用。比如下位机复位后串口缓冲区里可能残留上一次的数据不清理的话程序会读到一堆过期的旧数据。ser.reset_input_buffer()第四pyserial的Serial类还支持with语句上下文管理with serial.Serial(COM3, 9600, timeout1) as ser: ser.write(bping\n)这样无论程序中途怎么出错退出串口都会被自动关闭省心很多。说实话我在实际项目里装pyserial的次数已经数不过来了但每次帮同事排查发现大半问题都出在环境选择上而不是安装命令本身。装这个库最核心的经验就一句话先确认终端里的Python和PyCharm运行代码用的Python是同一个再谈安装。只要这个前提成立pip install pyserial一次就能过剩下的所谓疑难杂症基本上都是网络源和解释器路径的问题。希望这篇梳理能帮你少走点弯路尤其是第一次用HC05蓝牙模块或者倒腾串口设备的时候回头再看这篇应该能省下不少折腾时间。 
长河君 · 2026/9/21 16:44:03 · 阅读 1.2k PyCharm安装pyserial全攻略：从pip报错到串口联调实战
前阵子做一个小工具要用HC05蓝牙模块和电脑串口通信结果在PyCharm里第一步就栽在了装pyserial上。这个库看着简单网上一搜教程满天飞可真照着操作下来各种报错照样能把人绕晕“pip不是内部或外部命令”“Permission denied”“No module named serial”……我索性把整个安装过程重新捋了一遍把踩过的坑和验证过的方法都记录下来写成了这篇东西。pyserial是Python操作串口的事实标准库包名叫pyserial可代码里导入时却写import serial。一个名字搞两套很多人第一次就懵了。这篇文章适合刚学Python串口通信、准备接HC05蓝牙模块、L298N电机驱动这些硬件的外包开发者也适合在PyCharm里装第三方包经常莫名其妙报错的人。看完你不仅能装好pyserial还能学会一套排查Python包安装问题的通用思路。1. 先把pyserial这件事看明白再动手1.1 pyserial到底是个啥包名和模块名为何不一样pyserial是一个第三方Python库专门用来和电脑上的串口Windows里叫COM口Linux里叫tty设备交流数据。几乎所有用Python做嵌入式开发、硬件调试的人都绕不开它。它的功能说白了就是三件事打开串口、往串口发数据、从串口读数据。但这里有个特别容易让人犯迷糊的点PyPI上的安装包名字是pyserial写代码时导入的模块名却是serial。所以你看网上的教程安装命令是pip install pyserial可代码第一行永远都是import serial。如果你哪天看到有文章写“import pyserial”那基本可以断定作者没真正跑过代码。还有一些老资料会提到serial这个包名其实PyPI上也有一个叫serial的第三方包但它和pyserial完全是两回事千万别搞混否则你装了一堆依赖代码照样跑不起来。pyserial本身的优点是跨平台Windows、Linux、macOS都能用而且同时支持Python 2和Python 3依赖极少整个安装包也就几百KB。按道理说这种轻量级库不应该装出问题但实际操作里大家还是经常翻车原因绝大多数都不在pyserial本身而是环境配置有问题。所以我一直觉得解决安装报错的第一步不是反复重装库而是先把自己的Python环境看清楚。1.2 安装前必须确认的三样东西无论你打算用哪种方法安装动手前都建议先确认下面三件事能省掉后面一大堆排查时间。第一当前项目用的Python解释器是谁。打开PyCharm看右下角状态栏那里会显示当前解释器的名字和路径。如果你有多个Python版本比如系统里同时装了Python 3.9、3.11还装了Anaconda那就必须搞清楚PyCharm现在用的到底是哪一个。因为pip install装到的是当前终端激活的那个Python不一定就是你代码运行用的那个Python。第二项目有没有创建虚拟环境。PyCharm新建项目时默认会创建venv虚拟环境如果你一路点“Next”没注意项目就会带着一个venv目录。打开PyCharm底部的Terminal如果命令行前面有(venv)几个字说明终端已经自动激活了虚拟环境此时pip安装的所有包都会进入这个虚拟环境不会污染系统Python。这是最理想的状态。如果命令行前面啥都没有说明终端使用的是全局Python包会装到系统目录。第三pip版本和网络源是否正常。执行python -m pip --version可以查看pip版本和它对应的Python路径如果这条命令能正常打印出版本号说明Python和pip基本没问题。至于网络源国内默认源是pypi.org经常抽风下文会细说怎么换镜像源。1.3 为什么明明是“装库”却经常要查环境很多人在网上搜“pycharm安装教程”跟着做了半天最后还是装不上pyserial就开始怀疑是不是PyCharm这个软件有问题。其实真不怪PyCharmPyCharm只是一个编辑器加项目管理工具它本身不负责管理Python包包管理是pip和Python解释器的事。问题往往出在解释器配置不一致上。举个例子你在PyCharm的Settings里看到Python Interpreter指向A环境的Python但打开Terminal时命令行实际用的却是B环境的Python。这俩如果不一致你就可能遇到“图形界面里看包已经装上了代码一运行照样No module found”的诡异现象。另外PyCharm新版界面和旧版不一样2020年之后的版本Settings入口和Package对话框都改过网上搜到的教程如果截图很老对不上号也很正常不影响本质思路。所以在进入安装环节之前我建议大家先把“当前解释器是谁”“有没有虚拟环境”“pip归谁管”这三个问题搞清楚。这三句话搞明白后面无论装什么包成功率都会高一大截。2. PyCharm中安装pyserial的3种高效方法2.1 方法一用PyCharm的Terminal跑pip命令这是我最推荐的方式也适合绝大多数场景因为你能看到完整日志遇到错误可以直接看到原因。操作步骤很简单打开PyCharm在当前项目里点击底部Tool Windows里的Terminal或者通过菜单View切换出来。确认命令行前面有(venv)前缀。如果没有用cd命令进入项目根目录然后手动激活虚拟环境。Windows下执行venv\Scripts\activatemacOS或Linux下执行source venv/bin/activate。执行安装命令pip install pyserial如果网络很慢或者反复超时就加上国内镜像源pip install pyserial -i https://pypi.tuna.tsinghua.edu.cn/simple安装成功后最后几行会显示Successfully installed pyserial-3.5看到这个就说明已经装好了。这里我想多说一句关于python -m pip install和pip install的区别。当系统里存在多个Python版本时直接用pip这个命令调用的可能是你最先装的那个Python的pip这不一定是你需要的。而python -m pip install pyserial会强制使用当前命令行里Python对应的pip更稳妥。在PyCharm的Terminal里只要虚拟环境激活正确python和pip就都是虚拟环境里的用哪个都行但出了PyCharm自己开终端的时候这个细节特别重要。另外如果你发现pip版本太老可以先升级pip再装库python -m pip install --upgrade pip老版本pip在解析一些新包的元数据时会出问题偶尔会出现明明包存在但它说找不到版本的情况。2.2 方法二在Python Interpreter里图形化安装不习惯命令行的朋友可以用PyCharm自带的图形化安装界面这种方式的好处是能直观看到当前解释器路径不容易装错环境。具体步骤打开PyCharm点击菜单File下拉里选择SettingsmacOS上是在PyCharm菜单里找Preferences。左侧栏展开Project:你的项目名找到Python Interpreter。右侧顶部会显示当前解释器的完整路径先确认这里选中的是你项目实际使用的解释器。点击路径右侧的号按钮弹出Available Packages搜索窗口。在搜索框输入pyserial下方列表过滤出这个包。点击左下角Install Package按钮。安装过程中左下角有进度条如果一直停在进度条通常是网络问题等一会儿或者换成国内源。换源的方法是点击左下角Manage Repositories先把默认的官方源地址解绑再添加清华源或阿里源保存后重新搜索安装即可。这个方法对新手特别友好因为它把解释器路径明明白白写在了界面上你能确认包到底装到了哪个环境里。不过它的缺点是一旦安装失败提示往往比较笼统只弹出一个Install failed具体原因还得去日志里翻。所以如果图形化安装失败我还是建议回到Terminal里执行pip install看看完整报错。2.3 方法三离线whl文件安装如果你所在的电脑完全不联网或者处于内网办公环境那离线安装就是救命方案。提前在一台联网电脑上把whl文件下载好拷贝过去就能装。步骤在一台能联网的电脑上打开浏览器访问pypi.org搜索pyserial找到Files列表下载这个文件pyserial-3.5-py2.py3-none-any.whl。把这个whl文件用U盘或者内部传输工具拷贝到目标电脑。在PyCharm的Terminal里执行本地安装命令pip install D:\downloads\pyserial-3.5-py2.py3-none-any.whlLinux或macOS就把路径换成对应的绝对路径或相对路径。这里有个通用知识点值得记一下whl文件名里的py2.py3-none-any是平台标签意思是对Python 2和Python 3都兼容且不依赖特定操作系统任何平台都能装所以pyserial的whl文件去哪里都通用。但以后如果你要离线安装pandas、numpy这类带C扩展的库文件名里会有类似cp39-cp39-win_amd64这样的标记必须和目标机器的Python版本、操作系统版本严格匹配不能随手拿一个就能装。pyserial是纯Python包才敢这么随便。离线安装完同样会提示Successfully installed之后想卸载也很简单pip uninstall pyserial即可。2.4 三种方法怎么选一张表看懂安装方式适用场景优点缺点Terminal pip日常开发网络正常日志清晰容易排查问题推荐首选需要稍微懂一点命令行Python Interpreter图形界面新手或者想确认解释器路径界面直观不容易装错环境失败提示笼统排错能力弱离线whl断网、内网隔离环境不受网络影响稳定可控需要提前下载文件复杂包还要匹配平台我个人建议是网络条件允许就优先用第一种方法因为你以后装任何包都会遇到报错熟悉命令行pip的报错逻辑对排查问题非常有帮助。图形化安装适合第一次接触PyCharm的新手先把东西装成功建立起信心再说。离线安装属于特殊场景掌握思路就好。3. 常见报错与排查方法3.1 pip命令提示“不是内部或外部命令”这是Windows用户最容易撞上的报错完整提示是“pip不是内部或外部命令也不是可运行的程序或批处理文件”。这个报错的本质是系统在PATH环境变量里找不到pip也就是说Python可能没装好或者装的时候没勾选Add Python to PATH。最简单的规避方法就是在PyCharm的Terminal里操作不要自己另外开一个cmd窗口。因为PyCharm已经配置好了解释器Terminal会继承这个环境一般不会出现找不到pip的情况。如果PyCharm的Terminal里也提示找不到pip那要检查Python解释器本身是否正常。更稳妥的命令是python -m pip install pyserial这条命令会先去找python再让python自己去找pip模块。如果python本身能运行pip一般是没问题的。如果连python都不认识那就得重新安装Python安装时务必勾选Add Python to PATH装完再重启PyCharm。还有一种情况提示的不是pip找不到而是pip后面报一堆traceback说No module named pip。这大概率是Python环境被弄坏了或者用的是某些精简版Python。遇到这种情况可以试一下python -m ensurepip --upgrade把pip重新安装回来。3.2 网络错误、超时和“No matching distribution”换源解决这种报错的长相五花八门常见的有Retrying (Retry(total4, connectNone, readNone, redirectNone, statusNone))...Could not find a version that satisfies the requirement pyserial (from versions: none)ERROR: No matching distribution found for pyserial前两种多半是网络或者源的问题最后一种除了网络问题也可能是pip版本太旧。很多人一看到“No matching distribution”就开始怀疑是不是包名错了其实包名没错就是下载通道不顺畅。解决办法是换国内镜像源。一次性命令pip install pyserial -i https://pypi.tuna.tsinghua.edu.cn/simple如果想永久生效以后懒得每次加参数可以在用户目录下创建一个pip配置文件。Windows用户在C:\Users\你的用户名\AppData\Roaming\pip下创建pip.ini或者直接在用户目录下新建pip文件夹再建pip.iniLinux和macOS用户在~/.pip或者~/.config/pip下创建pip.conf。文件内容如下[global] index-url https://pypi.tuna.tsinghua.edu.cn/simple trusted-host pypi.tuna.tsinghua.edu.cn保存后再执行pip install pyserial之后的所有pip安装都会走清华源。注意trusted-host这行不能省否则有些网络环境下会报SSL证书问题。另外如果确认网络没问题但就是提示找不到版本先把pip升级到最新版再试。老版本pip对某些新包的元数据解析会有问题升级方法上文已经写过。3.3 PermissionError权限不足别一味给管理员权限这类报错也很常见尤其在macOS或Linux上提示通常长这样Could not install packages due to an EnvironmentError: [Errno 13] Permission denied: /usr/local/lib/python3.11/site-packages/...本质上是当前用户没有权限往系统级Python目录里写入文件。很多人遇到这个第一反应是加sudo或者以管理员身份运行其实这是最不推荐的做法。因为系统Python环境是很多工具共享的你不小心污染了后面其他项目全都会遭殃。正确的做法是给项目创建虚拟环境然后在虚拟环境里安装这就不会存在权限问题。PyCharm项目的venv目录就是干这个用的。如果你实在不想建虚拟环境又只想给当前用户安装可以执行pip install --user pyserial这个命令会把包安装到当前用户目录下避免写系统目录。但“user安装”会增加环境复杂度不太建议长期依赖。顺便说一句Windows下如果提示Permission denied可以右键PyCharm图标选择“以管理员身份运行”来临时解决但这同样是治标不治本的办法。真正稳妥的还是用虚拟环境隔离干净。3.4 明明安装成功import serial还是No module found这是所有人最崩溃的情况屏幕明明显示Successfully installed pyserial代码里import serial却报ModuleNotFoundError: No module named serial。排查顺序我建议按下面几步来第一步确认当前终端环境。在PyCharm的Terminal里看命令行有没有(venv)前缀。如果没有说明pip把包装到了全局环境而PyCharm运行代码时用的可能是虚拟环境两边对不上。解决办法是激活虚拟环境后重新安装。第二步查看Python解释器路径。在Terminal里执行python -c import sys; print(sys.executable)看输出的路径是否和PyCharm右下角显示的解释器路径一致。如果不一致说明终端和PyCharm用的根本不是同一个Python这需要你在Settings里把解释器路径统一起来。第三步直接测试导入。执行python -c import serial; print(serial.__version__)如果这一步成功说明装到哪里都没问题那问题就出在PyCharm的索引或者运行配置上试试File菜单里的Invalidate Caches / Restart把缓存清掉再重开项目。还有一个不起眼但真实存在的坑你装的是pyserial结果代码里import的也是serial但系统里恰好有个不相关的serial包抢占了模块名。用pip show serial和pip show pyserial分别查看如果发现serial不是pyserial提供的那就卸载掉不相关的那个。我自己就遇到过这种情况装的包和模块名刚好撞车排查了半天。3.5 新系统上的PEP 668和conda环境报错这两年随着Linux发行版更新不少用户会遇到一个看起来莫名其妙的报错error: externally-managed-environment This environment is externally managed这是PEP 668引入的保护机制目的很朴素某些Linux发行版对Python系统环境进行了严格管理不允许pip直接往里装第三方包避免把系统包管理器维护的Python弄乱。如果你确认不需要动系统环境正解还是创建虚拟环境在venv里装。如果你确实无所谓想强行装可以用pip install --break-system-packages pyserial但这属于破坏性操作风险自负我一般不推荐。另外用Anaconda作为解释器的用户也要留心。你在PyCharm里打开了Terminal默认可能激活的是conda的base环境pip install会装到base里。如果你的项目用的是另一个conda环境就得先执行conda activate环境名再执行pip install pyserial。这类问题看终端提示符就能判断命令行前面出现的是(base)还是(venv)一眼就能看懂。为了方便大家对照排查我做了一个速查表报错信息最常见原因推荐解法pip不是内部或外部命令Python未加入PATH或未安装用python -m pip重装PythonRetrying / timeout官方源网络不稳定换清华、阿里等镜像源Could not find a version网络或pip版本太旧换源先升级pipPermissionError: [Errno 13]无权限写系统目录创建venv虚拟环境ModuleNotFoundError解释器或环境不一致统一解释器路径externally-managed-environment新版Linux系统保护用虚拟环境No module named pipPython环境损坏python -m ensurepip4. 装好后的验收和实际联调经验4.1 三步快速验证版本号、解释器路径、导入测试装完pyserial先别急着写一大段业务代码用三步确认环境没问题再往下走。第一步在PyCharm的Terminal里执行python -c import serial; print(serial.__version__)正常会输出3.5之类的版本号。如果没报错说明模块导入没问题。第二步执行python -c import sys; print(sys.executable)把输出路径和PyCharm右下角的解释器路径对一下确认代码运行用的就是刚装包的那个环境。这两条命令加起来用不了十秒钟但能避免绝大多数“装完还是跑不了”的尴尬。第三步在PyCharm的Python Console里执行import serial如果也没报错那环境基本就稳了。之后再去写连接硬件的代码心里才有底。4.2 用pyserial列出电脑上所有可用串口写串口程序的第一步通常不是直接打开某个端口而是先看看电脑有哪些串口可用。pyserial自带的list_ports工具就能做这件事代码非常简单import serial.tools.list_ports ports serial.tools.list_ports.comports() for port in ports: print(port.device, port.description)这段代码在Windows上会输出类似COM3 USB-SERIAL CH340这样的信息在Linux上会输出/dev/ttyUSB0之类的路径。强烈建议把这段逻辑封装成一个小函数每次启动程序时先枚举一遍串口再把结果打印给用户选择。很多嵌入式调试工具都是这么设计的避免用户手动填端口号填错。如果你插上了USB转TTL模块但这段代码根本看不到新端口那基本可以断定是驱动问题比如CH340芯片的驱动没装好或者线材本身有问题。这时候Python代码再对也白搭得先把系统层面的设备识别搞定。4.3 接HC05蓝牙等硬件时连接不上的四个原因装好pyserial、也看到了串口不代表就能立刻和HC05蓝牙模块正常通信。网上搜“hc05蓝牙模块连接不上”能搜出一堆求助帖结合我的经验最常见的其实是这四个原因。第一个是USB转TTL驱动问题。HC05模块自己不带USB接口必须通过USB转TTL小板连接电脑小板上的主控芯片通常是CH340或者CP2102。如果Windows设备管理器里根本看不到COM口或者显示黄色感叹号那就先装对应芯片的驱动再回来讨论Python程序。第二个是COM口号认错。系统分配的COM号可能会因为插拔顺序发生变化比如上一次是COM3下一次变成COM5。不要图省事把COM3硬编码在代码里用上文说的list_ports枚举设备才是正经做法。第三个是波特率不匹配。HC05模块有命令响应模式和透传模式不同模式下默认波特率不一样常见的有9600、38400、115200。pyserial打开串口时设置的波特率必须和蓝牙模块一致否则你往串口发出一堆数据对面收不到或者收到的全是乱码。这种问题光看代码是看不出来的得先确认模块那边的参数。第四个是TX和RX接反或者模块供电不足。串口通信的接线原则是交叉相连设备的TX接USB转TTL的RX设备的RX接USB转TTL的TX。第一次接硬件的人特别容易把这两根线按“同名相连”来接然后发现数据死活不通。电源方面有些HC05模块需要3.3V或5V供电电流不够时会表现为搜索不到蓝牙或者连接后频繁断开。pyserial打开串口的标准代码是import serial try: ser serial.Serial(COM3, 9600, timeout1) print(打开串口成功, ser.name) except serial.SerialException as e: print(打开串口失败, e)注意timeout参数一定要写不然执行ser.read()时如果对端一直不发数据代码就会一直卡在阻塞状态看起来像程序死机。4.4 和L298N电机驱动、ESP32等设备联调的代码思路很多人装pyserial之后第一个项目就是控制小车用L298N电机驱动模块接电机再用单片机接收电脑指令。在这种场景里Python端一般不是直接操作L298N而是通过pyserial往下位机比如Arduino或STM32发指令由下位机解析后控制电机。往串口发数据的代码很简单ser.write(bforward\n)注意write方法接收的是字节类型不是普通字符串。如果你手头是字符串需要先编码data forward ser.write(data.encode(utf-8))读取数据时readline可以按行读取适合下位机按行返回状态信息的场景line ser.readline() print(line.decode(utf-8, errorsignore))如果收到的数据是乱码除了前面说的波特率问题还要检查通信双方的串口参数数据位、停止位、校验位是否一致。pyserial默认是8位数据位、1位停止位、无校验这个参数和大多数单片机默认配置一致但如果下位机改了配置Python这边也要跟着改。至于ESP32这类板子很多人会顺手扩展以太网功能比如LAN8720模块。这种以太网扩展严格来说已经不走串口通信了而是走SPI或者RMII接口和pyserial关系不大。但你在串口调试阶段还是需要pyserial从ESP32的日志串口读取打印信息所以把它装好、理解串口基本用法依然有价值。4.5 几个容易看懵的pyserial接口细节最后补充几个我实际使用中经常见人搞混的接口细节省得你们踩同样的坑。第一程序的串口对象用完一定要关闭ser.close()程序退出时不会自动释放串口资源如果你反复运行调试就会遇到serial.SerialException打开失败原因是串口被上个进程占用尤其是Windows上特别明显。第二in_waiting属性可以帮你判断缓冲区里有没有数据if ser.in_waiting 0: data ser.read(ser.in_waiting)这个比直接sleep然后read更高效能减少CPU空转。第三flush和reset_input_buffer这类方法在实际联调时很有用。比如下位机复位后串口缓冲区里可能残留上一次的数据不清理的话程序会读到一堆过期的旧数据。ser.reset_input_buffer()第四pyserial的Serial类还支持with语句上下文管理with serial.Serial(COM3, 9600, timeout1) as ser: ser.write(bping\n)这样无论程序中途怎么出错退出串口都会被自动关闭省心很多。说实话我在实际项目里装pyserial的次数已经数不过来了但每次帮同事排查发现大半问题都出在环境选择上而不是安装命令本身。装这个库最核心的经验就一句话先确认终端里的Python和PyCharm运行代码用的Python是同一个再谈安装。只要这个前提成立pip install pyserial一次就能过剩下的所谓疑难杂症基本上都是网络源和解释器路径的问题。希望这篇梳理能帮你少走点弯路尤其是第一次用HC05蓝牙模块或者倒腾串口设备的时候回头再看这篇应该能省下不少折腾时间。