How to Resolve "ModuleNotFoundError: No Module Named 'celery'" in Python

The ModuleNotFoundError: No module named 'celery' is a common error encountered when working with asynchronous task queues in Python. Celery is a distributed task queue library that allows you to run time-consuming operations (like sending emails, processing images, or generating reports) in the background, outside of your main application flow. This error simply means Python cannot find the Celery package in your current environment.

In this guide, you will learn what causes this error, how to diagnose the root issue, and how to fix it across different scenarios including virtual environments, Docker containers, and IDE configurations.

What Causes This Error?

The ModuleNotFoundError is raised when Python's import system searches all directories in sys.path and cannot find a module matching the name you specified. For Celery specifically, the most common causes are:

1. Celery is not installed in the current Python environment.
2. Wrong Python interpreter: Celery is installed for a different Python version or environment.
3. Incorrect module name: a typo or wrong casing in the import statement.
4. Virtual environment not activated: Celery is installed in a virtual environment that is not active.

Reproducing the Error

import celery

Output:

Traceback (most recent call last):
  File "main.py", line 1, in <module>
    import celery
ModuleNotFoundError: No module named 'celery'

Solution 1: Install Celery

The most common fix is simply installing the package. Use pip to install Celery:

pip install celery

For Python 3 specifically (if your system has both Python 2 and Python 3):

pip3 install celery

Verify the Installation

After installing, verify that Celery is available:

python -m pip show celery

Expected output:

Name: celery
Version: 5.3.6
Summary: Distributed Task Queue.
Home-page: https://docs.celeryq.dev/
...

Or verify directly in Python:

import celery
print(celery.__version__)

Output:

5.3.6

Solution 2: Fix the Module Name (Case Sensitivity)

Python module names are case-sensitive. The correct import uses all lowercase:

import Celery

import CELERY

import celery

When importing the Celery class from the module, note the difference between the module name (lowercase) and the class name (capitalized):

from celery import Celery

app = Celery('tasks', broker='redis://localhost:6379/0')

Solution 3: Activate Your Virtual Environment

If you installed Celery inside a virtual environment, you must activate that environment before running your script:

source venv/bin/activate

venv\Scripts\activate

python -m pip show celery

If Celery is not installed in the virtual environment:

pip install celery

Solution 4: Check Your IDE's Python Interpreter

If the error occurs in your IDE (VS Code, PyCharm, etc.) but not in the terminal, your IDE may be using a different Python interpreter than the one where Celery is installed.

VS Code

1. Press Ctrl+Shift+P (or Cmd+Shift+P on macOS).
2. Type "Python: Select Interpreter".
3. Choose the interpreter that has Celery installed (e.g., your virtual environment's Python).

PyCharm

1. Go to File → Settings → Project → Python Interpreter.
2. Verify the selected interpreter matches the environment where Celery is installed.
3. If not listed, click the gear icon and add the correct interpreter.

Solution 5: Install in a Docker Container or CI/CD Pipeline

If you are running your application in Docker, ensure Celery is included in your requirements.txt and installed during the build:

requirements.txt:

celery==5.3.6
redis==5.0.1

Dockerfile:

FROM python:3.11-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
CMD ["celery", "-A", "tasks", "worker", "--loglevel=info"]

Diagnostic Checklist

If the error persists after trying the solutions above, work through this checklist:

Installing Celery With Common Extras

Celery often requires a message broker (like Redis or RabbitMQ) and can be installed with optional dependencies:

pip install "celery[redis]"

pip install "celery[librabbitmq]"

pip install "celery[redis,auth,msgpack]"

Quick Verification Script

Run this script to confirm everything is set up correctly:

import sys

print(f"Python: {sys.executable}")
print(f"Version: {sys.version}")

try:
    import celery
    print(f"Celery version: {celery.__version__}")
    print("✅ Celery is installed and importable.")
except ModuleNotFoundError:
    print("❌ Celery is NOT installed in this environment.")
    print(f"   Install it with: {sys.executable} -m pip install celery")

Output (when Celery is installed):

Python: /home/user/project/venv/bin/python
Version: 3.11.5 (main, Sep 11 2023, 08:31:25)
Celery version: 5.3.6
✅ Celery is installed and importable.

Output (when Celery is NOT installed):

Python: /home/user/project/venv/bin/python
Version: 3.11.5 (main, Sep 11 2023, 08:31:25)
❌ Celery is NOT installed in this environment.
   Install it with: /home/user/project/venv/bin/python -m pip install celery

Conclusion

The ModuleNotFoundError: No module named 'celery' is almost always caused by one of four issues: Celery is not installed, it is installed in a different Python environment, there is a typo in the import name, or the virtual environment is not activated.

The fix is straightforward: install Celery with python -m pip install celery in the correct environment, ensure your IDE is configured to use that same environment, and always use the lowercase module name celery in your import statements. Running python -m pip show celery is the quickest way to confirm whether the package is available in your current Python environment.