Skip to content
Tutorials Center
My learning

Topics

Lesson 75 of 77 ยท Practice and Review

Common Django Mistakes

Seven Django mistakes that bite every team, each with a live before and after: N+1 queries, shared defaults, circular imports, migration conflicts and more.

Most Django bugs are not exotic. They are the same dozen mistakes, repeated by every team, usually in the first year of a project. They tend to work fine in development with five rows of data and then fall over in production with five million, or they hide for months until two developers merge their branches on the same day.

This lesson walks through the mistakes that cost the most time. Each section shows the mistake, why it happens, and the fix, and wherever possible the example is live, so you can see the wrong behavior with your own eyes instead of taking our word for it.

The mistakes, in rough order of how often they cause trouble:

  1. The N+1 query problem
  2. Defaults that are shared or evaluated too early
  3. Circular imports between apps
  4. Conflicting migrations
  5. Overusing signals
  6. Fat views
  7. Running with DEBUG = True in production

A short list of smaller slips follows at the end.

1. The N+1 query problem

The ORM makes it easy to follow relationships, and that is exactly the trap. Reading book.author looks like an attribute access, but when the author has not been loaded it runs a query. Put that inside a loop and a page that should need one query needs hundreds: one query for the list, plus one more for each row.

The same happens in reverse: calling author.books.count() inside a loop runs one query per author. The ORM performance lesson covers the tools in depth; here is the problem and its fix side by side.

flowchart LR
    subgraph Before["Before: N+1"]
        A1["SELECT books"] --> A2["SELECT author 1"]
        A1 --> A3["SELECT author 2"]
        A1 --> A4["SELECT author N"]
    end
    subgraph After["After: select_related"]
        B1["SELECT books<br/>JOIN authors"]
    end

Without a join, the number of queries grows with the number of rows; with select_related it stays at one.

Python N+1 queries, before and after

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

With 15 books and 5 authors, the slow versions run 16 and 6 queries, and the fixed ones run exactly 1. Now imagine 10,000 rows. Use select_related for forward foreign keys and one-to-one fields, prefetch_related for reverse and many-to-many relations, and annotate when you only need a number. Make it a habit to open the debug toolbar or call CaptureQueriesContext on any list page you write, and pin the count in a test with assertNumQueries.

2. Defaults that are shared or evaluated too early

Two related mistakes live in the default= argument of a field.

A mutable default instance. JSONField(default=[]) hands the same list object to every new row. Mutate it on one instance and the change appears on the others. Django warns you: the system check fields.E010 reports a default that should be a callable. The fix is to pass the callable itself: default=list or default=dict.

A default that runs at import time. default=timezone.now() calls the function once, when the module loads, so every row gets the time the server started. default=timezone.now (no parentheses) passes the function and Django calls it for each new object. The editor below shows the effect with a counter instead of a clock, so the output stays the same on every run.

Python Frozen defaults and mutable defaults

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The frozen column holds 1 for every ticket, because next(clock) ran once while the class body executed. The fresh column counts up because Django calls next_ticket each time. The system check flags only bad_tags, and tells you why. Run python manage.py check regularly (it also runs before runserver and in CI) so warnings like this never reach a release.

3. Circular imports between apps

When orders/models.py imports Customer from customers/models.py, and customers/models.py imports Order from orders/models.py, Python starts importing the first module, jumps to the second, and finds the first one half finished. The name you asked for does not exist yet, and you get an ImportError that mentions a "partially initialized module".

The live example below reproduces this with two tiny in-memory modules, so you can see the real error message, and then applies the simplest fix: import inside the function that needs the name.

Python A circular import and its fix

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Django gives you better tools than a local import, because most circular imports in a project are between models:

Python
# orders/models.py
class Order(models.Model):
    # A string "app_label.ModelName" is resolved lazily, so no import is needed.
    customer = models.ForeignKey("customers.Customer", on_delete=models.CASCADE)

For code that is not a model field, call django.apps.apps.get_model("customers", "Customer") at run time. Longer term, circular imports usually mean two apps know too much about each other. Move the shared piece into a third app, or let one app depend on the other in only one direction.

4. Conflicting migrations

Two developers branch from the same commit. Each runs makemigrations, and each gets a file called 0002_... that depends on 0001_initial. Both are merged. The migration graph now has two leaf nodes for the same app, and migrate stops with "Conflicting migrations detected".

flowchart TD
    M1["0001_initial"] --> M2A["0002_add_price<br/>(branch A)"]
    M1 --> M2B["0002_add_stock<br/>(branch B)"]
    M2A --> M3["0003_merge"]
    M2B --> M3

A conflict is two leaves; a merge migration depends on both and joins them again.

Django can model this graph for you. The example below builds the three migrations as graph nodes and asks the loader for conflicts before and after the merge node exists. (Real projects use the makemigrations --merge command, which writes the merge file.)

Python Detecting a migration conflict

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

To avoid the mess in the first place: pull and run migrate before you create a migration, commit migration files together with the model change, and never edit or delete a migration that others have already applied. If you do hit a conflict, run python manage.py makemigrations --merge, read the generated file, and commit it. See the migrations lesson for squashing and data migrations.

5. Overusing signals

Signals look convenient: "whenever an order is saved, write an audit entry". But they hide the flow of the program, they run in an order you do not control, and, most surprisingly, they do not fire for every write. bulk_create(), update() and delete() on a queryset skip save(), so the receiver stays silent while the data changes anyway.

Python A signal that does not fire

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Three orders exist, yet the audit log knows about only one. The explicit create_orders() function is boring, easy to find with a text search and easy to test, which is exactly what you want. Use signals for reacting to code you do not own (such as the built-in User model) and keep your own business rules in plain functions or model methods. The signals lesson has more on when each approach fits.

6. Fat views

A view should translate HTTP into a function call and the result back into HTTP. When it also contains discount rules, loops over every row and formatting code, the only way to test the rules is to simulate a web request. Duplication follows, because the next endpoint needs the same rule.

The fix is to move domain logic where it belongs: filtering into a custom QuerySet (see custom managers), per-object rules into model methods or properties, and multi-step workflows into service functions. The two views below return identical JSON; only one of them can be tested without a request.

Python A fat view and a thin view

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The thin version also does the filtering and sorting in the database instead of loading every book into Python, so it scales better. Whenever a view grows past a screen of code, ask what could move out of it.

7. Running with DEBUG = True in production

DEBUG = True is a development convenience that turns your site into an information leak. Error pages show source code, local variables, the settings, SQL queries and the full list of your URL patterns. It also makes Django remember every SQL query in memory, which slowly eats RAM on a busy server. On top of that, ALLOWED_HOSTS is not enforced the same way in debug mode.

The tzdata line is only needed in the browser: Django looks up its default time zone, and Pyodide has no time zone database. The editor sends two requests, a missing page and a crashing view, once with DEBUG on and once off. The override_settings helper changes the setting for a block of code, and the test client with raise_request_exception=False returns the 500 page instead of raising.

Python What DEBUG exposes

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

With DEBUG = True, even the customer's e-mail address in a local variable ends up in the HTML of the error page. With DEBUG = False, visitors see a plain error page and the details go to your logs. The last line shows two warnings from python manage.py check --deploy: security.W018 (DEBUG is on) and security.W020 (ALLOWED_HOSTS is empty). Run that command before every release, load DEBUG and SECRET_KEY from environment variables, and read the security lesson and the deployment lesson for the full checklist.

Smaller slips worth knowing

These are quick to fix once you know them. The editor demonstrates the first four.

  • Saving in a loop. Five save() calls run five inserts; bulk_create() runs one.
  • Loading rows just to count them. len(queryset) fetches every row; count() asks the database for a number.
  • Using if queryset: to test for emptiness. It loads everything; exists() runs a tiny SELECT 1 query.
  • get() where zero or many rows are possible. It raises DoesNotExist or MultipleObjectsReturned; use filter(...).first() or catch the exception.
  • Forgetting commit=False. When you modify a ModelForm instance before saving, call form.save(commit=False), set the extra fields and save yourself, then call save_m2m() if the form has many-to-many fields.
  • Putting secrets in settings.py. Read SECRET_KEY, passwords and API keys from environment variables and never commit them.
  • Changing AUTH_USER_MODEL late. Decide on a custom user model before the first migration.
  • Running without tests. Even a few tests for views and models catch most regressions (see the testing lesson).
Python Small slips, measured

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Notice that every counting variant runs one query. The difference is in what the query returns: len() and if queryset: select every column of every row, while count() and exists() return a single value. With ten rows it does not matter; with ten million it is the difference between a snappy page and a timeout.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Which change fixes an N+1 problem caused by reading book.author inside a loop?

    select_related joins the author table into the same query, so book.author no longer triggers a new query for each row.
  2. 2. Why is default=timezone.now() (with parentheses) on a model field a bug?

    With parentheses you pass the result of one call, not the function. Without them Django calls the function for each new object.
  3. 3. A post_save receiver writes audit entries. Which operation will NOT trigger it?

    QuerySet.update() and bulk_create() write to the database without calling save(), so post_save is never sent for those rows.
  4. 4. What is the cleanest way to reference a model from another app in a ForeignKey when importing it would create a circular import?

    A string reference 'app_label.ModelName' is resolved lazily by Django, so neither module has to import the other at import time.
  5. 5. What is the main risk of leaving DEBUG = True on a public server?

    Technical error pages show code, variables and configuration to anyone who triggers an error, and DEBUG also keeps every query in memory.

Summary

  • Count queries on list pages; fix N+1 with select_related, prefetch_related or annotate, and pin the count with assertNumQueries.
  • Pass callables as defaults (default=list, default=timezone.now) and heed the fields.E010 check.
  • Break circular imports with string model references, apps.get_model() or a local import, and reconsider the app boundaries.
  • Pull before makemigrations; resolve a conflict with makemigrations --merge and commit the result.
  • Signals miss bulk_create() and update() and hide the flow; prefer explicit functions for your own logic.
  • Keep views thin: queryset methods, model methods and services hold the rules.
  • Never deploy with DEBUG = True; run check --deploy and read settings from the environment.

Next lesson: Django Interview Questions.