Skip to main content

How to Resolve Python "ModuleNotFoundError: No module named 'flask_cors'"

When developing Flask web applications that need to handle Cross-Origin Resource Sharing (CORS), the Flask-Cors extension is commonly used. If you encounter the ModuleNotFoundError: No module named 'flask_cors', it means Python cannot find this extension when your application tries to import it (usually via from flask_cors import CORS). This almost always indicates that the package is not installed in the active Python environment.

This guide provides a clear walkthrough of the causes and step-by-step solutions to install Flask-Cors correctly.

Understanding the Error: Python's Import System & Flask Extensions​

Python uses its import system (sys.path) to locate modules. When you write from flask_cors import CORS, Python searches for a package named flask_cors. Flask-Cors is a third-party extension for Flask, not part of the standard library or Flask itself, so it needs to be installed separately using a package manager like pip. The ModuleNotFoundError occurs if the package wasn't installed or was installed into a different Python environment than the one running your Flask application.

Common Causes of the Error​

  • Package Not Installed: You simply forgot to run pip install Flask-Cors.
  • Incorrect Python Environment: The package was installed using a different pip (linked to a different Python version or environment) than the python interpreter running your Flask app.
  • Virtual Environment Not Activated: You installed the package globally but are running your app from within a virtual environment (or vice-versa), or you forgot to activate the correct virtual environment before running the app.
  • IDE Misconfiguration: Your IDE (VS Code, PyCharm) is configured to use a Python interpreter that doesn't have Flask-Cors installed.

Solution 1: Install the Flask-Cors Package (pip/conda)​

The most direct solution is to install the package into your project's active Python environment. Open your terminal or command prompt, navigate to your project's root directory, and ensure the correct virtual environment is activated.

  • Using pip (Standard):

    # Install Flask-Cors
    pip install Flask-Cors

    # Or use pip3 if that's your Python 3 pip
    # pip3 install Flask-Cors

    # Or use python -m pip if pip is not directly in PATH
    # python -m pip install Flask-Cors
    # python3 -m pip install Flask-Cors

    # If permission errors occur:
    # pip install Flask-Cors --user # Install to user directory
    # Or (use with caution):
    # sudo pip3 install Flask-Cors # Linux/macOS system-wide

  • Using conda (for Anaconda/Miniconda): The package might be available on certain channels. conda-forge is a common one.

    # Activate your conda environment first: conda activate your_env_name
    conda install -c conda-forge flask-cors
    # If not found on conda-forge, you might need to use pip within the conda env:
    # pip install Flask-Cors

After installation, restart your Flask development server and try accessing your application again.

Solution 2: Verify the Python Environment​

Consistency is key. Ensure the environment where you install Flask-Cors is the same one used to run your Flask app.

Checking Python Version​

Verify the versions associated with your python and pip commands.

python --version
pip --version

# Or:
python3 --version
pip3 --version

If you have multiple Pythons, ensure you use the matching pip (e.g., pip3.10 install Flask-Cors if running with python3.10).

Virtual environments prevent package conflicts and are standard practice for Python development.

  • Create (if needed): python3 -m venv venv (or your preferred name)
  • Activate:
    • Unix/macOS: source venv/bin/activate
    • Windows CMD: venv\Scripts\activate.bat
    • Windows PowerShell: venv\Scripts\Activate.ps1 (may require adjusting execution policy)
  • Install: pip install Flask-Cors (while the (venv) prompt is active)
  • Run Flask App: flask run or python your_app.py (while the (venv) prompt is active).

Checking IDE Interpreter Settings (VS Code, PyCharm)**​

Configure your IDE to use the Python interpreter located inside your activated virtual environment.

  • VS Code: Ctrl+Shift+P (or Cmd+Shift+P) -> "Python: Select Interpreter" -> Choose the Python executable from your venv/bin (Linux/macOS) or venv\Scripts (Windows) folder.
  • PyCharm: File -> Settings (or PyCharm -> Preferences) -> Project: [Your Project Name] -> Python Interpreter. Click the gear icon -> Add... -> Existing environment and point it to the Python executable within your virtual environment folder.

Debugging Steps​

If the error persists:

Check if the Package is Installed (pip show)​

Run this in your activated terminal/environment:

pip show Flask-Cors

# Or: 
python -m pip show Flask-Cors

If it says "Package(s) not found", it's definitely not installed correctly in that environment. If it shows details, check the Location: - does it point to the site-packages within your virtual environment?

Restart IDE / Development Server​

Sometimes IDEs or the Flask development server need a full restart to recognize changes in installed packages.

Reinstall / Upgrade the Package​

A clean installation might help.

pip uninstall Flask-Cors
pip install Flask-Cors

# Or try upgrading to the latest version
pip install --upgrade Flask-Cors

Basic Flask-Cors Usage Example​

Once installed and imported correctly, here's how you typically use it:

# Example Flask app (app.py)
from flask import Flask, jsonify
from flask_cors import CORS # Import CORS

app = Flask(__name__)

# ✅ Initialize CORS for your app
# Basic setup allows all origins:
CORS(app)
# For specific origins and options:
# CORS(app, resources={r"/api/*": {"origins": "https://yourfrontend.com"}})

@app.route("/")
def index():
    return "Hello, World!"

@app.route("/api/data")
def get_data():
    # This endpoint can now be called from different origins (browsers)
    return jsonify({"message": "This data is CORS enabled!"})

if __name__ == '__main__':
    app.run(debug=True) # Run the development server

Remember to import CORS from flask_cors and then initialize it with your Flask app object.

Conclusion​

The ModuleNotFoundError: No module named 'flask_cors' almost always means the Flask-Cors extension is not installed in the correct Python environment being used by your Flask application.

The primary solution is:

  1. Activate your project's virtual environment.
  2. Install the package using pip install Flask-Cors.
  3. Ensure your IDE and terminal are using the interpreter from that virtual environment.

By following these steps, you can reliably install the extension and resolve the import error, enabling CORS support in your Flask application.

Table of Contents