Skip to main content

a generic app to provide a simple breadcrumbs functionality in django projects

Project description

An app for generic breadcrumbs in Django (>= 1.4).

The idea is to make breadcrumbs out of parts of an url path. This application assumes that your url patterns are well structured. For example like this:

/                                               # root path
/application/                                   # root of an app/module
/application/object_type/                       # list of specific objects
/application/object_type/some_object/           # details of specific object
/application/object_type/some_object/edit/      # edit (or any other operations) of a specific object


  1. Install the package from PyPi. For example via pip:

    pip install django-url-breadcrumbs
  2. Add urlbreadcrumbs to INSTALLED_APPS:

  3. Make sure you have a request context processor django.core.context_processors.request in your TEMPLATE_CONTEXT_PROCESSORS.


Let’s assume you have your urls in a form:


from django.conf.urls import patterns, include, url
from myproject.views import some_view

urlpatterns = patterns('',
    url(r'^$', some_view, {'template' : 'index.html'}, name='index'),
    url(r'^test1/', include('test1.urls')),
) in application called test1:

from django.conf.urls import patterns, include, url
from test1.views import some_view

urlpatterns = patterns('',
    url(r'^example/$', some_view, {'template' : 't1.html'}, name='t1home'),

In order to define your breadcrumbs you can make a mapping in like this:

    'index'  : 'Home page',
    't1home' : 'Index page of Test1',

Then somwhere in your base template (lets call it base.html) you can write this:

{% load urlbreadcrumbs_tags %}
{% render_breadcrumbs %}

or you can specify your own template:

{% render_breadcrumbs "test1/mybreadcrumbs_template.html" %}

Also you can just include your breadcrumbs template:

{% include "test1/mybreadcrumbs_template.html" %}

But to use it like this make sure you’ve added a context procesor urlbreadcrumbs.context_processors.build_breadcrumbs in your TEMPLATE_CONTEXT_PROCESSORS setting.

In your template you have one additional context variable called breadcrumbs which is a list of two-tuples containing name and url of a breadcrumb. The default template used by django-url-breadcrumbs (urlbreadcrumbs/default.html) looks like this:

{% for n,u in breadcrumbs %}
    {% if not forloop.last %}
        <a href="{{ u }}">{{ n }}</a> &raquo;
    {% else %}
        {{ n }}
    {% endif %}
{% endfor %}

So now, assuming template t1.html is extending base.html, when viewing /test1/example/ you should see something like this Home page » Index page of Test1.

Another way of specyfing a name for a breadcrumb is to use a custom url function in your Instead of defining a mapping in URLBREADCRUMBS_NAME_MAPPING setting you can do this in of your ROOT_URLCONF and test1 application:

from django.conf.urls import patterns, include, url
from urlbreadcrumbs import url as burl

urlpatterns = patterns('',
    burl(r'^test1/', include(test1_urls)),


from django.conf.urls import patterns, include, url
from test1.views import some_view
from urlbreadcrumbs import url as burl

urlpatterns = patterns('',
    burl(r'^example/$', some_view, {'template' : 't1.html'}, name='t1home', verbose_name='Index page of Test1'),

This should work as in previous example.


Ideas and/or bug reports are welcome. Consider reporting an issue on

Pull requests are also welcome ;).

To start working on this app get the source from Bitbucket:

hg clone

and in a newly created virtualenv do this:

pip install -r dev_requirements.txt
python test


django-url-breadcrumbs uses pytest for running it’s test suite and tox for checking it’s compatibilty with different Python and Django versions.

In order to perform tests with your current python and django installation do this:

python test

To test it with different python and django versions run this:


Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

django-url-breadcrumbs-0.3.3.tar.gz (7.9 kB view hashes)

Uploaded source

Built Distribution

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page