PyCharm虚拟环境调试报错：RuntimeError: Can't determine home directory

错误详情 #

在PyCharm中调试debug_app.py时触发以下错误：

import lightgbm
File "C:\Users\work\ai_engine\virtuelenv\lib\site-packages\lightgbm\__init__.py", line 8, in <module>
from .basic import Booster, Dataset, Sequence, register_logger
File "C:\Users\work\ai_engine\virtuelenv\lib\site-packages\lightgbm\basic.py", line 20, in <module>
from .compat import PANDAS_INSTALLED, concat, dt_DataTable, is_dtype_sparse, pd_DataFrame, pd_Series
File "C:\Users\work\ai_engine\virtuelenv\lib\site-packages\lightgbm\compat.py", line 29, in <module>
import matplotlib
File "C:\Users\work\ai_engine\virtuelenv\lib\site-packages\matplotlib\__init__.py", line 890, in <module>
dict.update(rcParams, _rc_params_in_file(matplotlib_fname()))
File "C:\Users\work\ai_engine\virtuelenv\lib\site-packages\matplotlib\__init__.py", line 567, in matplotlib_fname
for fname in gen_candidates():
File "C:\Users\work\ai_engine\virtuelenv\lib\site-packages\matplotlib\__init__.py", line 564, in gen_candidates
yield os.path.join(get_configdir(), 'matplotlibrc')
File "C:\Users\work\ai_engine\virtuelenv\lib\site-packages\matplotlib\__init__.py", line 273, in wrapper
ret = func(**kwargs)
File "C:\Users\work\ai_engine\virtuelenv\lib\site-packages\matplotlib\__init__.py", line 510, in get_configdir
return _get_config_or_cache_dir(_get_xdg_config_dir)
File "C:\Users\work\ai_engine\virtuelenv\lib\site-packages\matplotlib\__init__.py", line 471, in _get_config_or_cache_dir
configdir = Path.home() / ".matplotlib"
File "C:\Python39\lib\pathlib.py", line 1143, in home
return cls(cls()._flavour.gethomedir(None))
File "C:\Python39\lib\pathlib.py", line 276, in gethomedir
raise RuntimeError("Can't determine home directory")
RuntimeError: Can't determine home directory

根源分析 #

从错误栈可看出，问题出在matplotlib初始化时调用Path.home()失败。Windows系统中Path.home()依赖USERPROFILE或HOME环境变量定位用户主目录，PyCharm调试环境可能存在以下问题：

• 环境变量未正确加载或缺失
• 虚拟环境权限不足，无法读取系统环境变量
• PyCharm缓存异常导致环境变量加载错误

修复方案 #

• 检查并添加调试环境变量

  1. 打开PyCharm的「Run/Debug Configurations」，选中目标调试配置
  2. 切换到「Environment variables」标签，点击右侧编辑按钮
  3. 检查是否存在USERPROFILE或HOME变量：
     • 若不存在，手动添加：变量名填USERPROFILE，值设为你的用户主目录（如C:\Users\work）
     • 若存在，确认值是否正确指向你的用户目录
  4. 保存配置后重新调试

• 强制指定matplotlib配置目录
  在debug_app.py的最开头添加以下代码，绕过Path.home()的自动检测：

  import os
  # 替换为你有权限读写的目录，比如用户目录下的.matplotlib或虚拟环境内文件夹
  os.environ['MPLCONFIGDIR'] = 'C:/Users/work/.matplotlib'
  

  也可直接在PyCharm调试配置的环境变量中添加MPLCONFIGDIR，值设为上述路径

• 检查虚拟环境权限
  右键点击虚拟环境目录C:\Users\work\ai_engine\virtuelenv，选择「属性」-「安全」，确认当前登录用户拥有该目录的读写权限，若缺失则添加对应权限

• 重置PyCharm缓存
  点击PyCharm顶部菜单「File」-「Invalidate Caches...」，选择「Invalidate and Restart」，重启后重新尝试调试

• 确认Python解释器配置
  打开「File」-「Settings」-「Project: xxx」-「Python Interpreter」，确认使用的是目标虚拟环境的解释器（C:\Users\work\ai_engine\virtuelenv\Scripts\python.exe），而非系统Python

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