搞嵌入式、物联网或者自动化测试的朋友十有八九会在 PyCharm 里跟 pyserial 这个模块打交道。串口通信是很多硬件项目绕不开的一环而 pyserial 往往是第一道坎——明明是几分钟就能装完的纯 Python 包实际动手时却可能被各种报错卡一晚上。我自己就在 PyCharm 里装这个模块踩过不少坑今天把三种常用方法、环境思路和常见报错的排查方案一次写清楚。文章内容偏向实操适合刚入门的学生、经常换电脑的工程技术人员以及在 Windows、macOS、Linux 之间来回切换的开发朋友。1. 安装前的关键认知PyCharm解释器与pyserial的关系1.1 pyserial到底是什么用在哪些场景pyserial 是 Python 社区最常用的串口通信库它把操作系统底层的串口读写能力封装成了统一的 Python 接口。你不需要关心 Windows 的 COM 口、Linux 的 /dev/ttyUSB0、macOS 的 /dev/tty.usbserial 在系统调用上有什么区别pyserial 会自动抹平这些差异。它的用法也很简单构造一个serial.Serial对象指定端口、波特率、超时时间然后就能read和write了。这个模块最典型的应用场景包括和 Arduino、STM32、ESP32 这类开发板通信调试 HC05 蓝牙模块、L298N 电机驱动板、GPS 模块、串口屏以及工业上常见的扫码枪、电子秤、传感器采集设备。说白了只要是走 UART 串口协议的硬件pyserial 基本都能接。正因为它太常用了做硬件开发的人几乎每新建一个项目都要装一次也就非常容易遇到“装不上”“装上用不了”的问题。1.2 为什么装了模块项目里还是找不到这个问题我见过太多回尤其是新手最容易蒙。明明在 PyCharm 的某个位置安装成功了回到代码里写import serial还是报ModuleNotFoundError。原因不在 pyserial 本身而在于 PyCharm 的虚拟环境机制。PyCharm 默认每个新项目都会创建一个独立虚拟环境virtualenv你可以把它理解成一个“项目专属的工具箱”。这个工具箱里有一套独立的 site-packages 目录用来存放当前项目安装的第三方库。你在 PyCharm 图形界面里装的包装的是当前项目对应解释器下的 site-packages你在系统命令行里用 pip 装的包装的可能是 Python 全局环境或另一个环境的 site-packages。两个环境互不相通所以会出现“系统里明明有 pyserialPyCharm 里却找不到”的情况。反过来也一样PyCharm 里能跑命令行里运行脚本却报错。所以安装 pyserial 之前第一件事不是急着敲命令而是确认“当前项目正在用的是哪一个 Python 解释器”。这一步确认了后面很多问题都会迎刃而解。1.3 动手前先确认当前项目用的解释器PyCharm 界面右下角状态栏一般会显示当前解释器路径长得像Python 3.11 (venv)这样。点击它可以看到更完整的信息也可以在这里快速切换解释器。更靠谱的方式是打开菜单栏SettingsMac 是 Preferences→ Project: 项目名 → Python Interpreter。这里会列出当前解释器的完整路径比如C:\Users\你的用户名\...\venv\Scripts\python.exe或者/usr/local/bin/python3。看到venv字样就说明项目在用虚拟环境。这种情况下你安装包的位置就锁定在这个 venv 目录里不需要也不应该装到系统全局。确认好解释器后再选择下面任意一种安装方法就不会出现“装了半天装错地方”的尴尬情况。2. 方法一在PyCharm图形界面里安装新手最稳2.1 五步完成安装的完整过程图形界面安装最适合新手也适合不常敲命令的同事。整个流程直观点几下鼠标就行。具体步骤是打开 PyCharm加载目标项目。进入 Settings → Project: 项目名 → Python Interpreter。在解释器信息列表右上角找到号按钮点击后会弹出可用包窗口。在搜索框输入pyserial下方列表会出现对应包注意包名和模块名的区别安装包里叫 pyserial代码里 import 时用的是 serial。选中后点击左下角Install Package等待进度条跑完窗口提示Package pyserial installed successfully就完成了。装完后可以立刻在代码区写一段验证import serial print(serial.VERSION)运行后不报错并打印出版本号说明安装成功。2.2 界面里的两个隐藏细节软件源和版本号图形界面安装看起来无脑但有两个隐藏细节会影响成功率。第一个是软件源。PyCharm 默认从官方 PyPI 源下载包如果你所在网络访问官方源很慢或者超时界面会一直卡在进度条。解决办法是在包管理窗口顶部的Manage Repositories里添加国内镜像源比如清华源https://pypi.tuna.tsinghua.edu.cn/simple添加后优先从镜像下载速度会快非常多。第二个细节是指定版本号。默认情况下 PyCharm 会安装最新版本但在某些老项目里最新版可能和项目内其他依赖产生冲突。这时候就不要直接点 Install先在左侧列表选中pyserial再在右侧Specify version下拉框里选一个项目要求的历史版本比如3.5然后安装。这个操作在命令行里也能做但图形界面对不熟悉 pip 参数的人更友好。2.3 界面安装卡顿的应对思路图形界面安装虽然稳定但偶尔会卡在Collecting pyserial或者Downloading这一步半天没反应。我的经验是先别急着杀进程多等一两分钟有时只是网络慢。如果超过五分钟还没动静基本可以断定是网络访问 PyPI 不稳定可以取消安装换用国内镜像源再试。还有一种情况是 PyCharm 的索引更新比较慢安装完成后你在代码里写import serial编辑器可能短暂飘红。这时候检查一下索引是否在后台更新等它跑完红色提示通常会消失。如果还是红的关掉项目重新打开一次强制刷新索引基本能解决。3. 方法二用PyCharm内置Terminal执行pip命令工程师日常3.1 打开Terminal前先确认路径环境用了三年 PyCharm 后我个人的习惯是安装各类包优先用内置 Terminal。它不像图形界面那样一层层点菜单一条命令解决问题还方便批量操作。但前提是你要学会看 Terminal 面板的提示符。在 PyCharm 底部找到Terminal标签并打开注意看命令行提示符前面的目录路径。正常情况下提示符前面会带着当前项目的虚拟环境路径比如(venv) C:\Users\你的用户名\PycharmProjects\demo如果能看到(venv)这一小段前缀说明当前终端已经自动激活了项目的虚拟环境你在这里执行的 pip install 会装进项目自己的 site-packages这是最理想的状态。如果前缀里面没有(venv)或者显示的是系统 Python 路径那就要小心了此时安装可能装错地方。3.2 常用安装命令与参数说明最简单的安装命令是pip install pyserial如果你的电脑上同时装了多个 Python 版本直接用pip可能指向了错误的那个。更稳妥的写法是用python -m pip明确指定当前解释器python -m pip install pyserialpython -m pip这种写法的好处是pip 始终跟着你当前命令行里解析到的 python 走不会被环境变量里乱七八糟的路径搞乱。需要指定版本时在包名后面加和版本号pip install pyserial3.5需要升级已经安装的旧版本用-U参数pip install -U pyserial需要同时卸载和重装可以先pip uninstall pyserial -y pip install pyserial这些命令我几乎每周都要用几遍慢慢就形成了肌肉记忆。3.3 镜像加速配置与pip通用参数如果网络环境不好Terminal 里安装比图形界面更容易看出问题因为错误信息会直接刷新在屏幕上。访问官方 PyPI 慢时最常见的错误是ReadTimeoutError或Connection timed out。这时候不用改系统配置直接在命令里加-i参数指定镜像源即可pip install pyserial -i https://pypi.tuna.tsinghua.edu.cn/simple为了让以后每次安装都自动走镜像可以执行一次配置命令pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple配置完成后pip 会优先从镜像源下载不仅装 pyserial 快装其他包也同样受益。还有一个参数值得记住--default-timeout100。这个参数用来调整网络请求超时时间默认 15 秒在弱网环境下太短加大到 100 秒能减少很多莫名其妙的失败。3.4 安装完怎么确认装进了正确的环境安装完成后不要急着写代码先确认一下模块到底装到了哪里。最直接的命令是pip show pyserial输出里会有一行Location: ...这就是 pyserial 解压后的 site-packages 路径。如果这个路径里包含当前项目的 venv 目录说明安装位置正确。如果不包含说明你装进了别的环境需要回到 3.1 节检查 Terminal 是否激活了正确的虚拟环境。也可以直接列出现有所有包确认pip list看到 pyserial 出现在列表里说明安装成功。4. 方法三用requirements.txt批量安装项目工程化4.1 requirements.txt适用于什么场景如果你只是在 PyCharm 里临时装一个 pyserial 做练习图形界面或单条 pip 命令就够了。但如果你参与的是一个正经项目项目成员多、依赖包动辄十几个那我强烈建议用 requirements.txt 管理依赖。requirements.txt 本质上就是一个文本文件每一行写一个依赖包的名字可以带上版本号。PyCharm 识别到这个文件后就能帮你一键安装里面的所有依赖。这个方法最大的价值在于项目复现新电脑上拉下代码后不用一个个包手动装安装全部依赖只花几十秒而且保证大家都用同一个版本不会出现“在我电脑上能跑到你电脑上报错”的经典问题。4.2 两种触发安装的方式第一种方式是利用 PyCharm 的文件感知能力。在项目的根目录新建一个requirements.txt写入 pyserial 依赖后PyCharm 通常会在打开这个文件的顶部弹出一条提示条大意是“项目有未安装的依赖是否安装”。点击安装即可PyCharm 会自动解析文件中列出的所有包并逐个装好。第二种方式是在 Terminal 里手动执行pip install -r requirements.txt这种方式更适合依赖较多、网络稍慢的场景输出信息清晰方便定位哪个包安装失败。我一般会把两种方式都告诉同事让他们根据自己习惯选择。4.3 版本锁定策略精确指定还是给范围requirements.txt 里写依赖版本有两种策略。一种是精确锁定pyserial3.5好处是版本完全一致复现环境最可靠。缺点是未来想升级时要手动改文件。另一种是给定版本范围pyserial3.4,4.0好处是安装时会自动选择满足条件的最新版缺点是不同时间安装的版本可能不完全相同存在潜在差异。对于 pyserial 这种更新不频繁、API 相对稳定的库我个人倾向于精确锁定主要版本即可。比如pyserial3.5既不担心兼容性问题也能让全项目组保持一致。对于其他更新活跃的库再用范围策略也不迟。4.4 配合虚拟环境实现项目一键复现requirements.txt 和虚拟环境是绝配。理想的流程是拉新代码后在 PyCharm 里创建或打开项目自带的 venv 虚拟环境然后在 Terminal 里执行pip install -r requirements.txt所有依赖装进项目自己的环境不污染系统全局。这时候再去运行项目成功率是最高的。如果项目原来没有 requirements.txt我建议你在环境调通后顺手生成一份pip freeze requirements.txt这个命令会把当前环境里的所有依赖精确导出到文件里。需要注意pip freeze会包含间接依赖也就是那些你并没有直接 import 但被其他库依赖的包它们也必须完整列出缺一不可。这份文件就是你项目的“环境快照”以后不管换电脑还是给同事都能一键还原。5. 常见报错解析与排错实录5.1 报错速查表下面把我在 PyCharm 里安装和使用 pyserial 时遇到的典型报错整理成速查表方便大家直接定位问题。报错信息大概率原因解决思路pip 不是内部或外部命令Python 未安装或环境变量没配好检查 Python 安装配置 PATH 环境变量Could not install packages due to an EnvironmentError: [WinError 5]Windows 下权限不足以管理员身份运行 PyCharm 或加--usererror: externally-managed-environmentLinux/Homebrew 系统环境禁止 pip 直接装创建虚拟环境在 venv 内安装ReadTimeoutError/Connection timed out网络访问 PyPI 不稳定加国内镜像源调整--default-timeoutModuleNotFoundError: No module named serial装错了解释器环境或根本没装上确认当前解释器用python -m pip安装ERROR: Could not find a version that satisfies the requirement pyserial通常是网络无法访问 PyPI换镜像源或检查网络DLL load failed while importing serial系统 VC 运行库缺失/环境异常安装 VC Redistributable重装 Python 或 pyserialPyCharm 安装按钮一直转圈网络慢、索引更新或源不可达换镜像源或改用 Terminal 安装5.2 提示“pip不是内部或外部命令”怎么办这条报错绝大多数发生在 Windows 上。原因很直白系统在 PATH 环境变量里找不到 pip 对应的可执行文件。出现这个情况不代表 Python 没装可能只是 Python 目录没有加入 PATH。排查步骤很简单打开命令提示符输入python --version。如果能正常显示版本说明 Python 是装了的。再输入where python查看 Python 安装目录。把 Python 的安装目录和它下面的Scripts目录一起加入系统 PATH。配置好 PATH 后重开 PyCharm 再试。需要提醒的是改环境变量之后已经打开的终端不会自动刷新必须重新打开 Terminal 面板或重启 PyCharm 才能生效。另一个更省事的办法是在 PyCharm 里直接使用项目解释器对应的 Terminal因为 PyCharm 已经自动处理了路径问题通常不会遇到pip 不是内部或外部命令。5.3 权限不足与externally-managed-environment权限类报错分两种。Windows 下常见的是[WinError 5] 拒绝访问通常是因为你要往系统 Python 的 site-packages 里写文件但当前用户没有足够的写权限。解决办法有两种一是用管理员身份重新打开 PyCharm再执行安装二是在命令后面加--user参数pip install --user pyserial加了--user后包会装到当前用户目录下的 site-packages不需要管理员权限。Linux 或 macOS Homebrew 环境下Python 3.12 之后很多系统解释器默认禁止用 pip 直接装包会报一个叫externally-managed-environment的错误。这个设计的本意是防止用户把系统 Python 环境搞坏。破解思路不是跟它硬刚而是老老实实创建虚拟环境。在 PyCharm 里新建项目时选择New environment using Virtualenv然后在这个虚拟环境里装 pyserial就不会再碰到这个限制了。不建议新手执行报错信息里提示的--break-system-packages除非你很清楚自己在干嘛。5.4 网络超时、下载失败与镜像源配置国内用户最容易遇到的就是网络问题。报错信息一般是WARNING: Retrying (Retry(total4, connectNone, readNone, redirectNone, statusNone)) after connection broken by ReadTimeoutError(...)翻译成人话就是pip 尝试连接 PyPI 下载但对方响应太慢超时了。遇到这种情况我的经验是不要反复重试直接切换镜像源。临时方案是在安装命令后追加pip install pyserial -i https://pypi.tuna.tsinghua.edu.cn/simple永久方案是配置全局 index-urlpip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple配置完之后你会发现不只是 pyserial其他包的安装速度也有明显提升。另外如果公司网络走的是代理还需要在 PyCharm 的 Settings → Appearance Behavior → System Settings → HTTP Proxy 里配置代理否则即使镜像源也连不上。5.5 安装成功却显示ModuleNotFoundError: No module named serial在所有安装问题里这个是最容易让人崩溃的Terminal 里 pip 明确显示安装成功但 PyCharm 运行代码时还是报ModuleNotFoundError: No module named serial。核心原因只有一个运行代码的解释器和安装包的解释器不是同一个。常见场景有两种。第一种你在系统终端里用系统 Python 的 pip 装了 pyserial但 PyCharm 项目用的是 venv 虚拟环境系统环境里装的东西项目根本看不到。第二种PyCharm 里同时配置了多个解释器A 解释器装了包但运行按钮用的是 B 解释器。排查方法很直接。在 PyCharm 的 Terminal 里执行python -c import sys; print(sys.executable)看打印出的路径是否和项目解释器一致。如果不一致要么切换解释器要么统一用python -m pip install pyserial重新安装。另外还可以在代码里临时加一句import sys print(sys.executable)运行后看控制台输出的解释器路径再和安装时 pip 的Location对比定位问题就很容易了。5.6 找不到满足要求的版本或版本冲突有时候你会看到这条报错ERROR: Could not find a version that satisfies the requirement pyserial ERROR: No matching distribution found for pyserial这条报错多数情况下不是真的“找不到版本”而是 pip 连不上 PyPI或者镜像源不可用。因为 pyserial 是纯 Python 包官方 PyPI 上一直存在不存在官方下架的情况。所以遇到这个报错优先检查网络换镜像源再试。另一种情况是版本冲突。项目里某个库要求 pyserial 版本必须小于某个版本而你安装了最新版就会产生依赖冲突。报错信息里一般会明确写出The conflict is caused by ...按提示降级 pyserial 就行pip install pyserial3.4我的建议是除非项目里有清晰的版本约束否则 pyserial 用 3.5 这个长期稳定版本就足够覆盖绝大多数硬件调试需求。5.7 Windows下import serial提示DLL加载失败这条报错比较吓人但实际出现频率不算高。pyserial 本身是纯 Python 写的理论上不存在编译型 DLL 依赖。如果 Windows 下import serial真的报出DLL load failed while importing serial那问题基本出在 Python 环境本身而不是 pyserial 的锅。常见原因是 Python 安装不完整或者系统里缺少 Microsoft Visual C Redistributable。解决办法按顺序尝试安装微软官方 Visual C Redistributablex64重装 Python安装时勾选“添加到 PATH”卸载 pyserial 后重新安装pip uninstall pyserial -y pip install pyserial用 Anaconda 环境替换原有的 Python 环境排查这类问题要冷静别一股脑重装系统。DLL 报错往往牵扯到 Visual C 运行时装好运行库后多数能解决。5.8 PyCharm安装按钮一直转圈卡死图形界面点安装后一直转圈等十分钟也没有结果这种情况我遇到不止一次。卡住的原因基本是网络问题但也可能是 PyCharm 的包索引和源同步出现了异常。处理建议分三步取消当前安装操作在包管理窗口的Manage Repositories中添加国内镜像源重新安装。镜像源也卡的话关掉图形界面安装切换到内置 Terminal 执行命令行安装。如果 Terminal 安装也卡住检查全局代理设置有时候代理配置错误会导致所有 HTTPS 请求挂起。说到底Terminal 里能看到详细日志比图形界面里一个干巴巴的进度条更容易定位问题。这也是为什么我后来在 PyCharm 里装包默认都先敲命令而不是点界面按钮。6. 装好pyserial之后快速验证与硬件联调经验6.1 三步验证安装结果装完 pyserial 后我建议别急着写完整通信代码先做三步快速验证。第一步验证模块可导入import serial print(pyserial version:, serial.VERSION)第二步验证串口列表是否可获取from serial.tools import list_ports ports list_ports.comports() for port in ports: print(port.device, port.description)如果你电脑上插了 USB 转串口设备、Arduino、蓝牙模块这一步应该能看到对应的端口号没插设备时输出可能为空这也不一定是问题。第三步尝试打开一个已知端口把 COM3 换成你自己的端口import serial ser serial.Serial(COM3, 9600, timeout1) print(open:, ser.is_open) ser.close()三步全部通过说明 pyserial 安装和环境配置都没问题了。6.2 串口设备识别与HC05、ESP32等场景的注意事项很多做硬件调试的朋友装好 pyserial 后第一个任务就是连 HC05 蓝牙模块或者 ESP32 开发板。这时候有一个高频坑值得单独提醒串口号搞错。以 HC05 蓝牙模块为例它通过 USB 转 TTL 模块连电脑时Windows 上通常会被识别成 COM3 或者 COM4但具体是哪个取决于驱动和USB插入顺序。如果你在设备管理器里看到的是 COM5代码里却写了 COM3那 open 时自然会报错。我一般会在连接硬件前专门写一段列出所有可用串口的脚本确认当前设备对应的端口号。还有一个经验是pyserial 打开串口以后这个串口就是独占的。如果你同时开着串口助手、Arduino IDE 的串口监视器再去运行 PySerial 脚本就会报PermissionError或SerialException: could not open port。解决办法是先关掉其他占用串口的软件再运行你的脚本。调试 HC05 时尤其要注意波特率配对模块默认常见的是 9600 或 38400主机和从机不一致时收发数据全是乱码但 pyserial 自身不报错这种问题最隐蔽。6.3 一段可以直接改的串口读写测试脚本验证完基本环境后我一般会用下面这段脚本做一轮简单的“发-收”测试确认整个链路通畅import serial import time ser serial.Serial( portCOM3, baudrate9600, bytesizeserial.EIGHTBITS, parityserial.PARITY_NONE, stopbitsserial.STOPBITS_ONE, timeout1, write_timeout1 ) # 发送 AT 指令HC05 蓝牙模块常用 cmd bAT\r\n ser.write(cmd) print(sent:, cmd) # 读取回应 time.sleep(0.5) data ser.read(64) print(recv:, data) ser.close()如果连接的是 AT 指令型的蓝牙模块发完AT\r\n后一般能收到OK回应如果连接的是单片机或传感器把指令换成你自己的协议帧就行。从安装到最后能收发数据整个过程不超过十分钟后面再复杂的功能都是在这个基础上扩展的。我在实际项目里最深的体会是pyserial 安装本身不复杂复杂的永远是环境不一致带来的“灵异现象”。所以我每次在新电脑上开工第一件事就是确认 PyCharm 项目的解释器路径第二件事是写一行import serial验证环境第三件事才是连硬件。如果你也被安装问题折腾过建议你也养成这个习惯能少走很多弯路。