Alpine镜像中Python包安装后Flask运行提示模块未找到求助

Hey there, this is a super common (and frustrating!) issue with Alpine-based Python images—let’s break down what’s probably going on and how to fix it.

First, let’s confirm the core contradiction: your package shows up in pip freeze, works in the Python shell, but fails when you run flask run. That means the problem is almost certainly a mismatch between the Python environment your shell uses and the one the flask command is leveraging.

Here are the most likely culprits and how to diagnose/fix them:

1. Mismatched Python Versions (Python 2 vs 3) #

Alpine’s default package setup often includes both Python 2 and 3, and sometimes pip points to Python 2 while python defaults to Python 3 (or vice versa). This creates a situation where your package is installed for one version, but Flask is using the other.

How to check: #

• Run python --version and flask --version to verify the Python versions match.
• Run which python and which flask to see their file paths. Open the flask script with cat $(which flask) to check its shebang line—this will tell you exactly which Python interpreter it’s calling.

Fix: #

• If Flask is using Python 2 but your package is installed for Python 3, reinstall Flask with pip3 install flask.
• Get into the habit of using explicit commands like pip3 and python3 instead of pip/python to avoid ambiguity in Alpine images.

2. Different sys.path Between Shell and Flask CLI #

Even if the Python versions match, the Flask CLI might be running with a different sys.path (the list of directories Python checks for modules) than your interactive shell.

How to check: #

1. Create a test script path_check.py:

   import sys
   print("Flask sys.path:")
   for p in sys.path:
       print(f"- {p}")
   from flask import Flask
   app = Flask(__name__)
   

2. Run it via Flask: FLASK_APP=path_check.py flask run
3. Compare the output to what you get in the Python shell:

   import sys
   for p in sys.path:
       print(f"- {p}")
   

Fix: #

If your package’s installation directory is missing from Flask’s sys.path, you can add it explicitly in your Flask app:

import sys
sys.path.append("/path/to/your/package")
# Rest of your app code

Or, ensure you’re installing the package to a directory that’s already in Flask’s sys.path (like using pip install --target=/usr/lib/python3.x/site-packages if that’s where Flask looks).

3. Non-Root User vs Root Installation #

If you’re running your Flask app as a non-root user in Docker, but installed the package as root without the --user flag, the non-root user might not have access to the installed modules (though this usually throws a permission error, not a "module not found").

How to check: #

• Run pip freeze as the same user you run Flask with. If the package isn’t listed, that’s the issue.

Fix: #

• Install the package with pip install --user . when running as the non-root user, or ensure the non-root user has read access to the site-packages directory.

4. Quick Test to Confirm Environment Mismatch #

Instead of using the flask command, run your app directly with Python: python your_app.py. If this works, the problem is definitely with the Flask CLI’s environment, not your package installation.

Content of the question originates from Stack Exchange, asked by Dhia