Generates URLs automatically from a model instance
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.

Django Model URLs

Build Status

This app makes urls usage DRYer. It maps URL keywords to a model object instance by passing the object instance as argument to the URL.

In short, having an article model instance, you can write this:

<a href="{{ url('article:detail', article) }}">View this article</a>

While you have been writing this so far:

<a href="{{ url('article:detail', year=article.year, month=article.month, slug=article.slug) }}">View this article</a>

This is for your templates as well as for your reverse() and preserves other urls to work.

Right now it is build for Jinja2 using the easy-to-use Jingo adapter. If you are using plain Django template, refer to version 0.3.1. A new version for plain Django should come out later on.


Download via pip pip badge

pip install django-model-urls

or get the bleeding edge version:

pip install git+

Add model_urls to your settings file:


And you're done!

How to use it

In the examples below we will consider this model:

class Article(models.Model):
    slug = models.SlugField()
    title = models.CharField(max_length=50)
    date = models.DateField()

    def year(self):

    def month(self):

and this urls:

urlpatterns = patterns('',
        ArticleView.as_view(), name="article_details"),

and article being an instance of the Article class.

In a template

url('article_details', article)

In a view

from model_urls.urlresolvers import reverse

reverse('article_details', article)

Both will generate a url in this format:


Extra tools

Basically you should be able to use url() and reverse() in all cases. However, these tools are also available:

Template helpers

  • url(viewname, *args, **kwargs) will try to detect an instance in arguments and choose wheter to use simple_url() or model_url() otherwise.
  • simple_url(viewname, *args, **kwargs) is an alias to Jingo's url() helper to force using it.
  • model_url(viewname, instance, *args, **kwargs) will generate the url from the instance in first argument.

Url reversing

These functions are available in model_urls.urlresolvers.

  • model_reverse(viewname, instance, urlconf=None, args=None, kwargs=None, prefix=None, current_app=None) will generate the url based on the instance properties.
  • reverse(viewname, *args, **kwargs) will fallback to model_reverse() if an instance is found in arguments or to Django's reverse() otherwise.


An optional configuration is for your settings is:


This option will not allow the Jingo's url() helper to be overriden by the one from model_urls.

In this case you should use model_url() to use an instance.

Further examples

Use cases

A common use case is switching from pk based url to slug. Using django-model-urls means updating the file to consider slug without altering views or template files.

Read tests

Refer to to see more usages.