Unable to Import 'celery' When Running pylint, but Django Runs Fine

I am working on a Django project and using uv as the package manager. My dependencies are managed in pyproject.toml, and I have the following setup:

pyproject.toml (Relevant Parts)

[project]
name = "port-backend"
version = "0.1.0"
description = "Backend service for port.az"
readme = "README.md"
requires-python = ">=3.12"
dependencies = [
    "celery>=5.4.0",
    "django==4.2",
    "djangorestframework>=3.15.2",
    "djangorestframework-simplejwt>=5.5.0",
    "drf-spectacular>=0.28.0",
]

[dependency-groups]
dev = [
    "pylint>=2.0.0",
]

[tool.pylint.MASTER]
ignore-paths = ['.venv/']
disable = [
    'C0415',  # Import outside toplevel
    'E0401',  # Import error
]

Steps Taken

  1. I ran uv sync, which created a new .venv and installed dependencies.

  2. VS Code detected the new environment and asked if I wanted to use it. I selected "Yes" and ensured the virtual environment was activated.

  3. Running uv run manage.py runserver works without issues, meaning Django and Celery are installed correctly.

  4. However, running uv run pylint . gives these errors:

************* Module manage
manage.py:12:8: C0415: Import outside toplevel (django.core.management.execute_from_command_line) (import-outside-toplevel)
************* Module config.celery_app
config/celery_app.py:3:0: E0401: Unable to import 'celery' (import-error)

What I Have Tried

  • Verified that Celery is installed in the .venv by running uv pip list, and celery is present.

  • Checked that the .venv is activated in VS Code (terminal shows (port-backend) ➜ port_backend).

  • Tried running uv run python -c "import celery"—this works without errors.

Question Why is pylint unable to find Celery (E0401: Unable to import 'celery'), even though Django and Celery run fine in manage.py? How can I make pylint recognize the installed dependencies correctly?

You might need to set PYTHONPATH to specify your root directory (Import outside toplevel).

Create a ~/.pylintrc file and change the /path/to/root to your root.

[MASTER]
init-hook='import sys; sys.path.append("/path/to/root")'

Pylint might not be picking up the .venv correctly. Try running:

PYTHONPATH=. uv run pylint .

Or modify your pyproject.toml:

[tool.pylint.MASTER] 
init-hook='import sys; sys.path.append(".venv/lib/python3.12/site-packages")'
Back to Top