Mac运行Django shell报No module named 'winreg'错误如何解决

问题背景 #

Mac系统下启动Django shell时触发ModuleNotFoundError: No module named 'winreg'报错。已知winreg是Windows系统专属的Python内置模块，仅随Windows版Python预装，正常Mac环境下不会被调用。
完整报错堆栈：

Traceback (most recent call last):
  File "/Users/j/code/myproject/core/manage.py", line 22, in <module>
    main()
  File "/Users/j/code/myproject/core/manage.py", line 18, in main
    execute_from_command_line(sys.argv)
  File "/usr/local/lib/python3.9/site-packages/django/core/management/__init__.py", line 446, in execute_from_command_line
    utility.execute()
  File "/usr/local/lib/python3.9/site-packages/django/core/management/__init__.py", line 440, in execute
    self.fetch_command(subcommand).run_from_argv(self.argv)
  File "/usr/local/lib/python3.9/site-packages/django/core/management/base.py", line 414, in run_from_argv
    self.execute(*args, **cmd_options)
  File "/usr/local/lib/python3.9/site-packages/django/core/management/base.py", line 460, in execute
    output = self.handle(*args, **options)
  File "/usr/local/lib/python3.9/site-packages/django/core/management/commands/shell.py", line 127, in handle
    exec(sys.stdin.read(), globals())
  File "<string>", line 5, in <module>
ModuleNotFoundError: No module named 'winreg'

排查定位方向 #

从堆栈中exec(sys.stdin.read(), globals())和<string>行报错特征可以判断，错误并非Django框架本身触发，是shell启动时执行的外部输入代码触发，按以下优先级排查：

• 首先检查传入Django shell的执行脚本：如果是通过管道、重定向方式启动shell（比如执行了python manage.py shell < your_script.py类命令），直接打开对应脚本查看第5行附近代码，排查是否存在直接import winreg的写法，或是脚本导入的第三方依赖为Windows专属包，内部调用了winreg模块。
• 全局检索项目代码中的winreg引用：在项目根目录执行全局搜索，查找所有包含winreg关键词的代码文件，重点检查跨平台逻辑是否遗漏系统判断。合规的跨平台代码会先判定运行系统再导入winreg，示例写法如下：

  import sys
  if sys.platform == "win32":
      import winreg
      # 仅Windows下执行的注册表操作逻辑
  

  如果代码中未加sys.platform判定，所有系统环境下都会直接导入winreg，就会触发Mac环境下的报错。
• 排查Python环境的依赖包污染：
  • 执行pip list查看当前环境已安装包，排查是否错误安装了Windows专属工具包（比如带win、windows、registry关键词的系统操作类包），定位后卸载对应包即可。
  • 如果使用虚拟环境，确认当前虚拟环境是在Mac本地创建，而非从Windows设备直接拷贝而来。跨系统拷贝的虚拟环境会残留大量平台专属依赖和路径配置，直接删除旧虚拟环境，在Mac端重新创建、重新安装requirements.txt中的依赖即可修复。
• 检查shell自动启动配置：排查是否配置了PYTHONSTARTUP环境变量指向的Python启动脚本、IPython启动配置、Django扩展的shell预执行脚本中包含winreg相关的Windows专属逻辑，这类脚本会在shell启动时自动执行，触发导入错误。

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