django-oscar: a domain-driven e-commerce framework you fork instead of configure

What django-oscar is for, and who ends up using it

Oscar describes itself as "an e-commerce framework for Django designed for building domain-driven sites", and the phrasing matters. This is not a storefront you install and theme. It is a Django application whose core functionality the README says "can be customised to suit the needs of your project", with the stated target ranging from "large-scale B2C sites to complex B2B sites rich in domain-specific business logic".

The audience that follows from that is narrow and specific: teams who already write Django, who have pricing, catalogue or fulfilment rules that no plugin system expresses, and who are willing to maintain a fork of the parts they change. A shop selling t-shirts with standard variants gets little from Oscar that a simpler Django shop would not also give. A distributor quoting contract prices per customer account, with stock split across warehouses, is closer to the case the framework was designed around.

One structural consequence is worth stating early. Because customisation happens by subclassing and overriding, the project's own abstraction is the thing you adopt, not just its features. That is a bigger commitment than adding a dependency.

How Oscar is put together: models, apps and overridable classes

Oscar ships as a set of Django apps under src/oscar in the repository, with the sandbox site living separately in sandbox/. The framework's central mechanism is the abstract model plus the concrete subclass: Oscar defines catalogue, basket, checkout, order, partner and offer models in a form intended to be inherited, so a project creates its own app, subclasses the Oscar model, and points Oscar at it. The documentation refers to this as overriding, and the same pattern applies to views and to the dashboard.

The dependency list in pyproject.toml shows what that machinery rests on. Categories are stored with django-treebeard, search runs through django-haystack, currency formatting uses Babel, phone numbers use django-phonenumber-field, and the basket page uses django-extra-views. None of those are incidental: they tell you the shape of the data model. A category tree, a search index that needs a backend configured, and a basket page that is a formset view.

The front end is built separately. package.json lists Bootstrap 4, jQuery, Select2, TinyMCE and Font Awesome as dev dependencies, compiled by gulp through the build and watch scripts. The Python package and the static assets are two build pipelines, which is why the Dockerfile installs Node alongside Python.

Installing django-oscar and running the sandbox locally

The PyPI package is django-oscar, and pyproject.toml declares requires-python >=3.8 with a Django range of django>=4.2,<6.2. A plain install pulls the runtime dependencies, including pillow, django-haystack, django-treebeard and Babel.

pip install django-oscar

After that, the README points at the sandbox as the fastest way to see the framework working. It states the sandbox site can be set up locally "in 5 commands" and links to a page in the documentation for the exact sequence; the repository also ships a Makefile and a sandbox/ directory, and the Dockerfile ends by running make install and make build_sandbox before starting uwsgi from /app/sandbox. The README does not reproduce those five commands inline, so the documentation page is the place to get them rather than guessing.

If you would rather not build anything, the README gives a second route: the sandbox is deployed as an official Docker image, oscarcommerce/django-oscar-sandbox, and is browsable at https://latest.oscarcommerce.com. That is the cheapest way to judge the dashboard and the checkout flow before you commit to the fork-and-override model.

For a real project the order of work is different. You install the package, add the Oscar apps to INSTALLED_APPS, create your own app that subclasses the models you need to change, and then run migrations. The documentation covers the fork procedure; the README itself does not walk through it.

The fork is the cost: migrations, upgrades and the LTS table

Overriding Oscar models means your project owns migrations for those models. The repository carries a requirements_migrations.txt file and a Makefile target for migrations, which is a signal of how much of the maintenance burden sits with you once you subclass. When Oscar changes a field on a model you have inherited, you are the one reconciling the migration history. That is the real price of the flexibility, and it does not appear in a feature comparison.

Version support is the second constraint. The README's supported-versions table lists 3.2 LTS as supported through January 2026, with 3.1 and 3.0 already past their end dates and 2.2 LTS supported through August 2023. LTS releases are defined as receiving an extended support period of three years, and support covers fixes for data loss bugs and security issues. The most recent releases are 4.2, 4.1 and 4.0, and the repository's last push was on 2026-09-11, so the project is being worked on, but the support table is what tells you whether your installed version will still receive security fixes.

Read that table before you start, not after. A team that pins 3.2 for stability and does not notice the January 2026 end date is running an unsupported branch.

When django-oscar is the wrong tool

The clearest failure mode is organisational rather than technical. Oscar assumes Python developers will be in the codebase. If the people operating the shop are merchandisers who need a hosted admin and a page builder, Oscar's dashboard is a Django dashboard, and every change to how it behaves is a code change with a deploy behind it. A hosted platform is a better fit for that team, and choosing Oscar means hiring for the gap.

The second case is API-first architecture. Oscar renders server-side Django views and templates; the README lists django-oscar-api as a separate stable extension for a "RESTful JSON API for django-oscar". If your storefront is a separate JavaScript application, you are adopting Oscar plus an extension, and you should read the extension's own documentation before assuming the combination is turnkey.

Third, if your requirements are genuinely ordinary, the abstraction is overhead. You will spend time learning Oscar's model layout and override conventions to arrive at something a few hundred lines of Django could have done, and you will carry the upgrade path described above for the privilege.

django-oscar against Saleor and the other Django commerce options

The comparison people search for is django-oscar versus Saleor, and the difference is architectural rather than a matter of feature checklists. Saleor is a separate application with a GraphQL API at its centre: you run its server, and your customisation happens through its API and its own extension points. Oscar is a library inside your Django project, and your customisation happens by subclassing its Python classes. One model asks you to integrate with a running service; the other asks you to maintain a fork.

That maps onto different teams. If you want a commerce backend your front end talks to over HTTP, and you are happy to run someone else's server, the API-first model is less work to start. If your business logic is entangled with your existing Django models (accounts, entitlements, internal pricing), keeping commerce inside the same process and the same ORM is the reason to choose Oscar.

Within Django itself, the honest alternative for a small shop is writing your own catalogue and order models. The README's own framing supports that reading: Oscar is aimed at sites "rich in domain-specific business logic", which is a description of the problem, not of the solution.

Licence, packaging and what an upgrade actually involves

Oscar is distributed under BSD-3-Clause; pyproject.toml declares the licence as BSD and the classifier as "License :: OSI Approved :: BSD License". That is a permissive licence, which matters for a framework you are expected to fork: your modified models remain your code. This is a description of the licence identifier, not legal advice, and the LICENSE file in the repository is the authoritative text.

One packaging detail is easy to miss. package.json declares "license": "MIT" for the JavaScript tooling side, while the Python package is BSD. The two files describe different things, and anyone auditing dependencies should read both rather than assuming a single licence covers the whole repository.

Upgrade cost follows from the override model. You move the pinned django-oscar version, resolve any dependency changes in your own requirements, and then reconcile migrations for every model you subclassed. The repository's requirements_migrations.txt and Makefile exist because the maintainers run that process themselves. Budget for it as recurring work, and check the supported-versions table each time you decide to stay put.

Editorial conclusion

Adopt django-oscar if you have Django developers on staff and your commerce rules do not fit an off-the-shelf storefront, and you accept that forking models means owning migrations and upgrades. Do not adopt it if you need a hosted admin you can hand to a non-technical operator, or if you want an API-first backend with no server-rendered pages. Before committing, verify two things: that your Django version falls inside the declared range of django>=4.2,<6.2, and that the extension you need (django-oscar-api, django-oscar-paypal, django-oscar-adyen) is listed as stable in the README rather than one you will have to write.

Frequently asked questions

Official sources

1. django-oscar/django-oscar on GitHub
2. License: BSD-3-Clause
3. Project website
4. README
5. Releases