Ubuntu下运行FastAPI服务遇websockets.datastructures模块缺失错误求助

问题描述 #

在Ubuntu系统中执行以下命令运行FastAPI服务时：

uvicorn.run("api:app", host="0.0.0.0", port=3100, reload=True, workers=10)

出现报错：

ModuleNotFoundError: No module named 'websockets.datastructures'

尝试执行pip3 install websockets时，日志显示下载websockets-10.3，但最终自动安装了websockets-8.1，问题仍未解决，完整报错堆栈如下：

Traceback (most recent call last):
  File "/usr/lib/python3.7/multiprocessing/process.py", line 297, in _bootstrap
    self.run()
  File "/usr/lib/python3.7/multiprocessing/process.py", line 99, in run
    self._target(*self._args, **self._kwargs)
  File "/home/hafid/.local/lib/python3.7/site-packages/uvicorn/_subprocess.py", line 76, in subprocess_started
    target(sockets=sockets)
  File "/home/hafid/.local/lib/python3.7/site-packages/uvicorn/server.py", line 60, in run
    return asyncio.run(self.serve(sockets=sockets))
  File "/usr/lib/python3.7/asyncio/runners.py", line 43, in run
    return loop.run_until_complete(main)
  File "/usr/lib/python3.7/asyncio/base_events.py", line 587, in run_until_complete
    return future.result()
  File "/home/hafid/.local/lib/python3.7/site-packages/uvicorn/server.py", line 67, in serve
    config.load()
  File "/home/hafid/.local/lib/python3.7/site-packages/uvicorn/config.py", line 471, in load
    ws_protocol_class = import_from_string(WS_PROTOCOLS[self.ws])
  File "/home/hafid/.local/lib/python3.7/site-packages/uvicorn/importer.py", line 24, in import_from_string
    raise exc from None
  File "/home/hafid/.local/lib/python3.7/site-packages/uvicorn/importer.py", line 21, in import_from_string
    module = importlib.import_module(module_str)
  File "/usr/lib/python3.7/importlib/__init__.py", line 127, in import_module
    return _bootstrap._gcd_import(name[level:], package, level)
  File "<frozen importlib._bootstrap>", line 1006, in _gcd_import
  File "<frozen importlib._bootstrap>", line 983, in _find_and_load
  File "<frozen importlib._bootstrap>", line 967, in _find_and_load_unlocked
  File "<frozen importlib._bootstrap>", line 677, in _load_unlocked
  File "<frozen importlib._bootstrap_external>", line 728, in exec_module
  File "<frozen importlib._bootstrap>", line 219, in _call_with_frames_removed
  File "/home/hafid/.local/lib/python3.7/site-packages/uvicorn/protocols/websockets/auto.py", line 17, in <module>
    from uvicorn.protocols.websockets.websockets_impl import WebSocketProtocol
  File "/home/hafid/.local/lib/python3.7/site-packages/uvicorn/protocols/websockets/websockets_impl.py", line 9, in <module>
    from websockets.datastructures import Headers
ModuleNotFoundError: No module named 'websockets.datastructures'

原因分析 #

1. websockets.datastructures模块是在websockets 9.0及以上版本中新增的，websockets 8.1不包含该模块，无法满足当前uvicorn版本的依赖要求。
2. 你使用的是Python 3.7，而websockets 11.0及以上版本不再支持Python 3.7，pip会自动降级安装兼容的最高版本（即8.1），导致安装的版本不符合uvicorn的需求。

解决方案 #

步骤1：卸载现有低版本websockets #

执行以下命令彻底卸载已安装的websockets：

pip3 uninstall -y websockets

步骤2：安装兼容Python3.7的指定websockets版本 #

选择既支持Python3.7又包含datastructures模块的版本，比如websockets 10.4（这是支持Python3.7的最后一个10.x版本）：

pip3 install websockets==10.4

步骤3：验证安装结果 #

执行以下命令确认安装的版本：

pip3 show websockets

输出中Version字段应为10.4，此时再运行你的uvicorn启动命令即可解决报错。

额外提示 #

注意：reload=True（开发重载模式）和workers=10（多进程模式）不能同时使用，uvicorn会自动忽略reload参数或者抛出警告，建议根据场景二选一：

• 开发环境用reload=True，去掉workers参数；
• 生产环境用workers=10，去掉reload参数。

内容的提问来源于stack exchange，提问作者Dany M