Linux下Python访问串口Permission denied错误排查

苏见山
苏见山
发布时间:2026-11-18| 9人浏览过
原创

深入排查Linux系统下使用Python访问串口出现Permission denied权限拒绝报错的根本原因,提供用户组授权、后台独占进程清理与udev规则持久化配置的完整实用解决方案。

适用环境:Linux (Ubuntu / Debian / Raspberry Pi OS / Fedora / Arch) 软件模块:Python 3 & pyserial 错误代码:[Errno 13] Permission denied
在 Linux 环境下运行 Python 脚本打开 /dev/ttyUSB0 或 /dev/ttyACM0 等串口设备时,遭遇 Permission denied: '/dev/ttyUSB0' 是嵌入式与硬件交互开发中最常见的报错。该错误的核心原因在于 Linux 严格的设备节点访问控制机制:串口设备属于系统特权节点,普通用户未被加入对应的设备授权组(如 dialout 或 uucp),或串口正被后台独占守护进程抢占。通过系统化的属组配置、进程解绑或 udev 规则固化,可以彻底解决这一问题。

一、报错复现与核心原因解析

当我们在 Python 中使用主流的 pyserial 库初始化串口实例时,典型的出错代码如下:

import serial

# 尝试打开 USB 转串口设备
ser = serial.Serial(port='/dev/ttyUSB0', baudrate=115200, timeout=1)

在默认配置的普通用户终端下,执行该代码往往直接中断并输出如下异常栈信息:

终端异常回显(示例)
serial.serialutil.SerialException: [Errno 13] could not open port /dev/ttyUSB0: [Errno 13] Permission denied: '/dev/ttyUSB0'

要理解该错误,需要明确 Linux 内核将硬件串口抽象为文件系统中的字符设备节点(Character Device)。在系统根目录的 /dev 下,串口设备拥有明确的文件属主(Owner)、所属组(Group)以及权限位模式(Mode)。

Linux下Python访问串口Permission denied错误排查
图 1:Linux 串口设备权限模型与用户访问判定逻辑

二、标准排查路径:用户组授权五步法

在绝大多数情况下,串口 Permission denied 报错是由于当前运行 Python 的用户尚未被赋予串口所在用户组权限所致。排查与解决应遵循严格的诊断步骤,切忌直接运行 chmod 777。

Linux下Python访问串口Permission denied错误排查
图 2:串口权限排查与修复标准操作流程

详细操作指令与输出分析

第一步:查询设备节点及其所属组

ls -l /dev/ttyUSB* /dev/ttyACM*
终端输出(示例)
crw-rw---- 1 root dialout 188, 0 10月 17 07:10 /dev/ttyUSB0

从输出中可以看到,第四列为设备所属组。在 Debian/Ubuntu 体系中通常为 dialout;在 Arch Linux 或 CentOS/Fedora 体系中,通常为 uucp。

第二步:核对当前用户是否属于该组

groups
终端输出(示例)
developer adm cdrom sudo dip plugdev lxd

如果输出列表中没有 dialout(或 uucp),则当前用户无权读写该设备节点。

第三步:添加用户至属组

根据不同发行版选择对应的组名进行授权:

# Ubuntu / Debian / Raspberry Pi OS
sudo usermod -aG dialout $USER

# Arch Linux / Manjaro / Fedora
sudo usermod -aG uucp $USER
重要注意事项: 必须使用 -aG(Append Group),千万不能写成单独的 -G。如果漏掉了 -a,usermod 将会把该用户从当前所有的附加组(包括 sudo 组)中清空,导致当前用户丧失管理员权限!

第四步:激活新组权限(常见避坑点)

很多开发者在执行完 usermod 后立刻再次运行 Python 脚本,发现依旧报 Permission denied,便误以为配置无效。实际上,Linux 进程的组凭证(Group Credentials)是在用户登录会话建立时一次性加载的,修改组数据库后,当前已打开的 Bash 会话并不会自动感知。

解决方法有两个:

  1. 临时激活当前终端:执行 newgrp dialout。该命令会启动一个已加载新组凭据的子 Shell。在此子 Shell 中运行 Python 脚本即可正常打开串口。
  2. 永久系统级生效:保存当前工作,注销当前桌面会话并重新登录(或重启系统),系统启动的所有进程与桌面终端将永久继承该组权限。

三、深入排查:设备被独占占用与后台进程冲突

如果用户已经在 dialout 组中,且通过 groups 命令确认凭证无误,但 Python 访问串口依然报 Permission denied 或 Device or resource busy,这通常说明设备节点正被 Linux 后台服务强行占用锁定,或被内核驱动层断开。

Linux下Python访问串口Permission denied错误排查
图 3:串口设备后台独占与冲突进程排查诊断机制

特别警惕:Ubuntu 22.04+ 中的 brltty 陷阱

在 Ubuntu 22.04 LTS 及更新版本中,许多开发者发现:当插入 USB 转串口模块(如 CH340 或 CP2102)时,/dev/ttyUSB0 会短暂出现 1~2 秒,随后设备文件离奇消失;如果在消失瞬间 Python 尝试打开它,就会触发异常。

通过执行 dmesg -T | grep -i usb 查看内核日志,通常能发现如下记录:

dmesg 内核日志(示例)
[2026-10-17 07:11:02] usb 1-1: ch341-uart converter now attached to ttyUSB0 [2026-10-17 07:11:04] usbfs: process 1245 (brltty) did not claim interface 0 before use [2026-10-17 07:11:05] ch341-uart ttyUSB0: ch341-uart converter now disconnected from ttyUSB0

根本原因:系统预装的 brltty 盲文终端后台驱动误将通用 USB 转串口芯片当成了盲文输入输出设备,直接将原生的 ch341 或 ftdi_sio 串口驱动卸载并独占。若不需要盲文设备,可通过以下命令彻底移除或屏蔽该服务:

# 停止并彻底屏蔽 brltty 服务
sudo systemctl stop brltty
sudo systemctl mask brltty

# 或者直接卸载软件包
sudo apt remove --purge brltty

操作完成后重新拔插 USB 串口模块,设备节点将恢复稳定挂载。

四、进阶方案:编写 udev 规则持久化权限与设备别名

除了全局将用户加入 dialout 组外,在生产环境或多串口嵌入式系统中,通常推荐通过编写 udev 规则实现两项能力:

  1. 永久指定权限位:确保任何普通用户均可免提权访问串口(如 MODE="0666")。
  2. 绑定固定别名(Symlink):避免当系统插入多个 USB 串口时,设备号随插拔顺序在 ttyUSB0、ttyUSB1 之间漂移,导致 Python 脚本路径硬编码失效。

1. 查询串口芯片的硬件特征码(VendorID 与 ProductID)

执行 lsusb 查看已连接的 USB 设备:

lsusb 输出(示例)
Bus 001 Device 005: ID 1a86:7523 QinHeng Electronics CH340 serial converter

在上述输出中,1a86 即为 idVendor,7523 为 idProduct。

2. 编写自定义 udev 规则文件

在 /etc/udev/rules.d/ 目录下新建规则文件(例如 99-custom-serial.rules):

sudo nano /etc/udev/rules.d/99-custom-serial.rules

在文件中填入如下规则(以 CH340 芯片为例):

# 匹配特定的 USB 串口芯片,赋予 0666 权限,并创建稳定软链接 /dev/myserial
SUBSYSTEM=="tty", ATTRS{idVendor}=="1a86", ATTRS{idProduct}=="7523", MODE="0666", GROUP="dialout", SYMLINK+="myserial"

3. 重新加载并触发 udev 规则

执行以下命令使新规则无需重启系统立即生效:

sudo udevadm control --reload-rules
sudo udevadm trigger

此时查看软链接与权限:

ls -l /dev/myserial
终端输出(示例)
lrwxrwxrwx 1 root root 7 10月 17 07:11 /dev/myserial -> ttyUSB0

在 Python 代码中,直接使用固定的 /dev/myserial 作为端口名即可:

import serial

ser = serial.Serial(port='/dev/myserial', baudrate=115200)

五、总结:排查决策树与最佳实践

遇到 Linux 下 Python 串口 Permission denied 报错时,请根据以下决策树逐步排查定位:

Linux下Python访问串口Permission denied错误排查
图 4:Linux 串口 Permission denied 排查决策树与总结

排查方法对比与适用场景

排查与修复方法 典型适用场景 生效持久性 安全性与规范性
usermod -aG dialout 个人开发机、测试工作站、树莓派单板 永久(需重新登录生效) 符合系统权限设计规范,推荐首选
停用 / 卸载 brltty Ubuntu 22.04+ 设备拔插后节点闪退 永久 彻底根除盲文服务抢占驱动问题
udev 规则配置 生产工控机、多串口设备绑定固定名称 永久(即插即用) 极高,可避免设备名在 ttyUSB0/1 间变动
fuser -k 释放占用 前序调试工具(minicom 等)异常崩溃 单次操作 应急排查手段,及时解除句柄独占
chmod 777(不推荐) 临时极速测试验证 极差(重新拔插即失效) 不安全,破坏系统权限安全隔离模型

Python 健壮性串口打开示例代码

在编写生产环境脚本时,建议在 Python 中加入针对 SerialException 的结构化异常捕获,在发生权限问题时给出明确的终端排查引导:

import sys
import serial
from serial.serialutil import SerialException

def connect_serial(port_name='/dev/ttyUSB0', baud_rate=115200):
    try:
        ser = serial.Serial(port=port_name, baudrate=baud_rate, timeout=2)
        print(f"成功打开串口: {port_name}")
        return ser
    except SerialException as e:
        error_msg = str(e)
        if "Permission denied" in error_msg:
            print(f"[错误] 权限不足无法访问串口: {port_name}", file=sys.stderr)
            print("排查建议:", file=sys.stderr)
            print(" 1. 请检查当前用户组: groups", file=sys.stderr)
            print(" 2. 执行授权指令: sudo usermod -aG dialout $USER", file=sys.stderr)
            print(" 3. 刷新凭证: newgrp dialout 或注销重登", file=sys.stderr)
            print(" 4. 检查是否被占用: sudo fuser -v " + port_name, file=sys.stderr)
        elif "NoSuchPort" in error_msg or "FileNotFoundError" in error_msg:
            print(f"[错误] 未检测到串口设备节点: {port_name},请检查硬件连接或 dmesg", file=sys.stderr)
        else:
            print(f"[错误] 串口通信异常: {e}", file=sys.stderr)
        return None

if __name__ == '__main__':
    ser = connect_serial('/dev/ttyUSB0')
    if ser and ser.is_open:
        ser.close()

通过清晰的权限模型认知、规范的用户组授权以及对后台干扰进程的精准排除,即可彻底杜绝 Linux 环境下 Python 访问串口的 Permission denied 困扰,确保硬件通信链路的稳定与可靠。

相关专题:

免责声明:本文内容仅供参考,不代表本站观点。转载或引用请注明出处。

Python 相关产品和应用

全部下载
Selenium

Selenium

4.51.0 · Windows

用于浏览器自动化和 Web 测试的 Python 工具。

scikit-learn

scikit-learn

1.9.1 · Windows

常用 Python 机器学习算法与模型评估工具库。

Black

Black

26.10.1 · Windows

强调一致性的 Python 自动代码格式化工具。

Ruff

Ruff

0.17.1 · macOS

由 Rust 编写的高速 Python 代码检查和格式化工具。

pytest

pytest

9.1.1 · Windows

简洁而强大的 Python 自动化测试框架。

FastAPI

FastAPI

0.146.0 · Windows

高性能 Python API 框架,支持类型提示和自动接口文档。

Flask

Flask

3.1.3 · Windows

轻量灵活的 Python Web 应用框架。

Django

Django

6.1.2 · Windows

成熟的 Python Web 框架,适合构建内容站点和业务系统。

Spyder

Spyder

6.1.7 · Windows

面向科学计算与数据分析的 Python 集成开发环境。

SciPy

SciPy

1.18.1 · Windows

面向科学、工程和技术计算的 Python 算法库。