HumanSignal/label-studio · critical · ImportError

Couldn't import Django. Are you sure it's installed and avai

Error message

Couldn't import Django. Are you sure it's installed and available on your PYTHONPATH environment variable? Did you forget to activate a virtual environment?

What it means

Standard Django bootstrap error re-raised by manage.py when importing django.core.management fails, meaning Django isn't installed or isn't importable in the current Python environment. The original ImportError is chained as __cause__.

Source

Thrown at label_studio/manage.py:18

#!/usr/bin/env python
"""This file and its contents are licensed under the Apache License 2.0. Please see the included NOTICE for copyright information and LICENSE for a copy of the license."""

import os
import sys

if __name__ == '__main__':
    os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'core.settings.label_studio')
    # os.environ.setdefault('DEBUG', 'True')
    try:
        from django.conf import settings
        from django.core.management import execute_from_command_line
        from django.core.management.commands.runserver import Command as runserver

        runserver.default_port = settings.INTERNAL_PORT

    except ImportError as exc:
        raise ImportError(
            "Couldn't import Django. Are you sure it's installed and "
            'available on your PYTHONPATH environment variable? Did you '
            'forget to activate a virtual environment?'
        ) from exc
    execute_from_command_line(sys.argv)

View on GitHub (pinned to 0b49e9b539)

Solutions

Activate the project's virtualenv: source <venv>/bin/activate (or `poetry shell` / `pipenv shell`)
Install dependencies: pip install -r deploy/requirements.txt or pip install label-studio
Run with the venv's interpreter explicitly: <venv>/bin/python label_studio/manage.py <cmd>
Check `pip show django` / `python -c 'import django'` to confirm installability

Example fix

// before
$ python label_studio/manage.py runserver  # system python, no Django
// after
$ source venv/bin/activate
$ pip install -r requirements/production.txt
$ python label_studio/manage.py runserver

Defensive patterns

Strategy: validation

Validate before calling

import importlib.util, sys
if importlib.util.find_spec('django') is None:
    sys.exit('Django not installed; activate your virtualenv and pip install -r requirements.txt')

Try / catch

try:
    from django.core.management import execute_from_command_line
except ImportError as exc:
    sys.stderr.write('Activate your virtualenv and install requirements.\n')
    raise SystemExit(1) from exc

Prevention

Always activate the virtualenv before running manage.py
Pin and install dependencies with pip install -r requirements.txt
Use the venv interpreter explicitly in scripts/CI: <venv>/bin/python manage.py
Verify environment with `python -c "import django; print(django.__version__)"`

When it happens

Trigger: Running `python label_studio/manage.py <command>` in an interpreter where the Django package is not installed or not on sys.path.

Common situations: Forgot to activate the virtualenv; installed dependencies with a different Python version (pip vs python3 mismatch); running from wrong directory with a bare system Python; partially installed requirements after a failed pip install.

Related errors

AI-assisted analysis of HumanSignal/label-studio@0b49e9b539 (2026-08-29). Data as JSON: /api/errors/6393312951226b39. Report an issue: GitHub.