Flask: ModuleNotFoundError: No module named flask and Environment Resolution

Verified FixPython 3.10+Flask 3.0+Silo: flask

Quick Fix / Solution Rapide

This error occurs when Python tries to import flask in an environment where Flask has not been installed or where the active interpreter does not match the virtualenv. Install Flask via python -m pip install flask.

Root Cause Analysis

This error occurs when Python executes a web application script or runs the Flask CLI (flask run) and attempts to execute import flask or from flask import Flask, but the active Python interpreter cannot find the flask package in any directory on sys.path.

Root Cause 1: Missing Package Installation in Current Virtual Environment

The most common cause is executing the script inside a freshly created virtual environment where pip install flask has not yet been executed. Python maintains isolated site-packages directories for each virtual environment; having Flask installed in global Python does not make it available inside an isolated virtualenv.

Root Cause 2: Running Terminal with Deactivated Virtual Environment

Developers often create a .venv directory but forget to activate it in the terminal session (source .venv/bin/activate on Linux/macOS or .venv\Scripts\activate on Windows) before running python app.py.

Root Cause 3: Multiple Python Interpeters in IDE (VS Code / PyCharm)

When using code editors, the integrated terminal may default to the system Python interpreter while the editor's language server uses a project virtualenv, causing code execution to fail even if autocomplete works.

Root Cause 4: File Naming Conflict (Shadowing)

If a file or directory in the project is named flask.py or flask/, Python will attempt to import that local module instead of the official library.

Reproduction Code (MCVE)

Example: Bug Reproduction

import sys

# Simulating an environment where flask is not present in sys.path
def verify_flask_installation():
    if "flask" not in sys.modules and not any("flask" in p for p in sys.path):
        raise ModuleNotFoundError(
            "ModuleNotFoundError: No module named 'flask'. "
            f"Active interpreter: {sys.executable}. "
            "Please run: python -m pip install flask"
        )

verify_flask_installation()

Solution 1: Install Flask in the Active Interpreter with python -m pip

Use python -m pip install flask to ensure Flask is installed into the exact interpreter executing your code.

Example: Recommended Solution

import sys
import os

# Solution 1: Verify interpreter location and installation command
print("Active Python Interpreter:", sys.executable)
print("Virtual Environment Active:", sys.prefix != getattr(sys, "base_prefix", sys.prefix))

# Terminal installation command for this specific interpreter:
install_cmd = f'"{sys.executable}" -m pip install flask'
print("Command to execute:", install_cmd)
assert os.path.exists(sys.executable)

Solution 2: Create and Activate a Dedicated Project Virtualenv

Create a clean virtual environment and install project dependencies from requirements.txt.

Example: Alternative Solution

# Solution 2: Virtual environment setup steps
setup_steps = [
    "python -m venv .venv",
    ".venv/Scripts/activate (Windows) or source .venv/bin/activate (Linux/Mac)",
    "python -m pip install --upgrade pip",
    "python -m pip install flask"
]

print("Setup procedure:")
for step in setup_steps:
    print(f"  $ {step}")

assert len(setup_steps) == 4

A frequent mistake is naming your application entry file flask.py. When you run python flask.py, Python attempts to import Flask from your own file instead of the package, resulting in AttributeError: partially initialized module 'flask' has no attribute 'Flask' or ImportError. Always name your file app.py, main.py, or wsgi.py.

Note de reproductibilité : Cette erreur dépend de l'isolation de l'environnement virtuel, des variables d'environnement système PATH et de la sélection de l'interpréteur dans votre éditeur de code.

Contrast ModuleNotFoundError: No module named 'flask' with ImportError: cannot import name 'Flask' from 'flask': The former indicates the package is completely absent; the latter indicates the package is found but corrupted or shadowed by a local file.

Previous Next