Give Your Django Admin X‑Ray Vision—Automatic Dead‑Link Detection

Most Django projects store some sort of URLs. Whether it's in a URLField() on some of your models or deep in some TextField()s full of HTML.

We all know cool URLs don't change, but not all URLs are cool and some rot over time. How do you find out which of your links have disappeared on you?

Turns out there is a Django app for that named django-linkcheck. It will check your URLs on a schedule you set and give you a nice admin page to manage dealing with them.

It helpfully gives you the status it received, links to recheck or ignore this item and quick 'Edit' links to take you right to the model object in question!

It hasn't had a release for awhile, but I can confirm it works just fine with Django 5.1.x. The docs are a bit sparse, so I stumbled around a little bit getting it to work. This post is here to save you from having to also stumble around in the dark.

Install and Setup

Installing the app is straight forward, you just add it to INSTALLED_APPS and include the special admin view in your main urls.py.

It then needs to create it's own tables so run:

$ ./manage.py migrate 

You then need to tell it which models and fields you want it to handle. The docs suggest you run:

$ ./manage.py linkcheck_suggest_config --model myapp.SomeModel > myapp/linklinks.py

Which is a great idea, but it's a bit broken actually. This generates something like:

from myapp.models import SomeModel

class SomeModelLinklist(Linklist):
    model = SomeModel
    url_fields = [myapp.SomeModel.url]
    ignore_empty = [myapp.SomeModel.url]
    object_filter = {"active": True}

linklists = {
    "SomeModel": SomeModelLinklist,
}

It fails to import Linklist for one, but the larger issue is it leads you believe you set the fields in the form <app>.<model>.<fieldname> when in fact it really needs to be just a list of modelfield strings. The correct version would be:

from linkcheck import Linklist   # actually import Linklist
from myapp.models import SomeModel

class SomeModelLinklist(Linklist):
    model = SomeModel
    url_fields = ["url"]   # list fields as strings 
    ignore_empty = ["url""]
    object_filter = {"active": True}

linklists = {
    "SomeModel": SomeModelLinklist,
}

This could be very confusing to a first time user or newer Django developer, but don't let that stop you. It's a really nice app that solves a real world issue.

Checking your links

To actually check your URLs from your models you then need to run two commands:

$ ./manage.py findlinks 

This populates linkcheck's tables with the TODO list of sorts.

You can then actually check them with:

$ ./manage.py checklinks 

NOTE: Both of these should be re-run periodically, perhaps via a cron job, based on your personal needs.

If you have any broken links they should be visible and ready to handle at /admin/linkcheck/ now.

Check out the README for more information on how you can set this up including settings for how frequently you would like the links to be rechecked.

Hopefully these small tips make it easier to start using this great Django app. Cheers!