NixOS下Flask项目遇ModuleNotFoundError：flask_wtf模块未找到

错误信息 #

Apr 24 21:18:04 nixos uwsgi[2261]: from flask_wtf import FlaskForm
Apr 24 21:18:04 nixos uwsgi[2261]: ModuleNotFoundError: No module named 'flask_wtf'

系统已安装包（configuration.nix） #

environment.systemPackages = with pkgs; [
  #  vim # Do not forget to add an editor to edit configuration.nix! The Nano editor is also installed by default.
    git
    wget
    pkgs.notepadqq
    pkgs.nginx
    pkgs.postgresql_16
    pkgs.pgloader
    pkgs.libgcc
    pkgs.python312
    pkgs.python312Packages.virtualenv
    pkgs.uwsgi
    pkgs.mariadb_114
    pkgs.kdePackages.okular
    pkgs.libreoffice-qt-fresh
    pkgs.spotify
    pkgs.fwupd
];

pip freeze 结果 #

虚拟环境外 #

[user@nixos:~]$ pip freeze
The program 'pip' is not in your PATH. It is provided by several packages.
You can make it available in an ephemeral shell by typing one of the following:
  nix-shell -p cope
  nix-shell -p python311Packages.pip
  nix-shell -p python312Packages.pip

虚拟环境内 #

(folder_env) 
[user@nixos:/var/www/folder/folder_env/bin]$ pip freeze
blinker==1.9.0
click==8.1.8
Flask==3.1.0
Flask-WTF==1.2.2
itsdangerous==2.2.0
Jinja2==3.1.6
MarkupSafe==3.0.2
psycopg2-binary==2.9.10
setuptools==78.1.0
Werkzeug==3.1.3
wheel==0.45.1
WTForms==3.2.1

问题 #

已在虚拟环境中安装 Flask-WTF，但 uWSGI 运行 Flask 应用时仍提示找不到 flask_wtf 模块，如何解决？

解决方法 #

1. 让 uWSGI 指向虚拟环境的 Python 解释器 #

uWSGI 默认可能调用系统 Python，而非虚拟环境版本。需在 uWSGI 配置中明确指定虚拟环境路径：

# 示例 uWSGI 配置文件内容
[uwsgi]
# 指向虚拟环境的 site-packages 目录
pythonpath = /var/www/folder/folder_env/lib/python3.12/site-packages
# 直接绑定虚拟环境根目录
home = /var/www/folder/folder_env
# 指定匹配的 Python 插件
plugin = python312

或者启动 uWSGI 时追加参数：

uwsgi --home /var/www/folder/folder_env --plugin python312 --wsgi-file your_app.py

2. 校验版本一致性 #

确保虚拟环境使用的 Python 版本（Python3.12）与 uWSGI 加载的 Python 插件版本完全匹配，避免版本不兼容导致模块无法识别。

3. 验证 uWSGI 的模块加载路径 #

在 Flask 应用中添加代码打印模块搜索路径，确认虚拟环境的 site-packages 目录是否被包含：

import sys
print(sys.path)

查看 uWSGI 日志，若输出路径中没有虚拟环境的 site-packages，说明 uWSGI 未正确加载虚拟环境。

4. NixOS 环境的额外配置 #

在 NixOS 中，可通过 nix-shell 包裹运行环境，确保依赖加载正确。创建 shell.nix 文件：

{ pkgs ? import <nixpkgs> {} }:
pkgs.mkShell {
  buildInputs = [
    pkgs.python312
    pkgs.python312Packages.virtualenv
    pkgs.uwsgi
  ];
}

执行 nix-shell 进入环境后，再启动虚拟环境和 uWSGI。

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