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

Ensure pip matches your Python interpreter

Use python -m pip to guarantee you are installing into the correct Python environment:

# ✅ Recommended: ensures pip matches the Python you're using
python -m pip install celery

# For Python 3 explicitly
python3 -m pip 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:

# ❌ Incorrect: wrong casing
import Celery
# ModuleNotFoundError: No module named 'Celery'

# ❌ Incorrect: wrong casing
import CELERY
# ModuleNotFoundError: No module named 'CELERY'

# ✅ Correct: all lowercase
import celery

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

# ✅ Correct: module is 'celery', class is 'Celery'
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:

# Linux / macOS
source venv/bin/activate

# Windows
venv\Scripts\activate

# Then verify
python -m pip show celery

If Celery is not installed in the virtual environment:

# Install within the activated environment
pip install celery

A common pitfall with virtual environments

Installing Celery globally (outside a virtual environment) does not make it available inside the virtual environment, and vice versa. Each environment has its own isolated set of packages:

# ❌ Installed globally, but virtual environment is active
pip install celery         # Installed globally
source venv/bin/activate
python -c "import celery"  # ModuleNotFoundError!

# ✅ Install within the activated environment
source venv/bin/activate
pip install celery         # Installed in venv
python -c "import celery"  # Works!

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:

Step	Command / Action	What to Check
1	python --version	Which Python version is running?
2	which python (Linux/macOS) or where python (Windows)	Which Python executable is being used?
3	python -m pip show celery	Is Celery installed for this Python?
4	python -m pip list | grep celery	Double-check the package list
5	python -c "import sys; print(sys.path)"	Is the install location in Python's search path?
6	Check IDE interpreter settings	Does the IDE use the same Python?

Installing Celery With Common Extras

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

# Celery with Redis support
pip install "celery[redis]"

# Celery with RabbitMQ support
pip install "celery[librabbitmq]"

# Celery with multiple extras
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.