django-oscar

4.1 verified Fri May 01 auth: no python

A domain-driven e-commerce framework for Django (current version 4.1). Designed for extensible, modular e-commerce sites. Release cadence: irregular, major versions every 1-2 years.

pip install django-oscar

Common errors

error ModuleNotFoundError: No module named 'oscar' ↓

cause django-oscar is not installed or not in the same virtual environment.

fix

Run pip install django-oscar and ensure you are in the correct environment.

error django.core.exceptions.ImproperlyConfigured: Application labels aren't unique, duplicates: oscar ↓

cause Multiple Oscar configs added to INSTALLED_APPS or using both old and new app config paths.

fix

Ensure only one Oscar app config is listed, e.g., 'oscar.OscarConfig'.

error ImportError: cannot import name 'OscarConfig' from 'oscar.apps' ↓

cause Using an old import path that was removed in Oscar 4.x.

fix

Change the import to from oscar import OscarConfig.

error django.core.exceptions.ImproperlyConfigured: The Oscar app must be listed first in INSTALLED_APPS ↓

cause Oscar must be loaded before other apps that depend on it.

fix

Move 'oscar.OscarConfig' to the first position in INSTALLED_APPS.

Warnings

breaking Oscar 4.x dropped support for Django < 3.2 and Python < 3.8. ↓

fix Upgrade Django to >=3.2 and Python >=3.8.

breaking Oscar 4.x removed the old 'oscar.apps.OscarConfig' direct module path; use 'oscar.OscarConfig'. ↓

fix Change INSTALLED_APPS from 'oscar.apps.OscarConfig' to 'oscar.OscarConfig'.

gotcha Oscar uses its own user model and registration. Custom user models must conform to Oscar's expectations or use the `oscar.core.loading` utilities. ↓

fix Use `from oscar.core.loading import get_user_model` instead of Django's default.

deprecated The dashboard feature is being gradually replaced with newer admin interfaces. Some dashboard views may become deprecated in future releases. ↓

fix Monitor Oscar changelog and consider using external admin packages.

Imports

OscarConfig
```
from oscar import OscarConfig
```
get_user_model
wrong
```
from django.contrib.auth import get_user_model
```
correct
```
from oscar.core.loading import get_user_model
```
Common mistake: users import Django's version, but Oscar's version handles custom user models correctly.

get_class

from oscar.core.loading import get_class

Quickstart

Initialize Oscar in a Django project (requires existing Django project with django-oscar installed). See official docs for full setup.

import os
os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'myproject.settings')
import django
django.setup()

from oscar import OscarConfig
OscarConfig.default_app_config = 'oscar.apps.OscarConfig'
# For a full project, use `oscar startproject myproject`