Skip to content
Switch branches/tags

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


Build Status

master:Build Status
develop:Build Status

An extensible, hierarchical, and pluggable navigation system for Django sites.

django-treenav was designed from the start to live independent of a CMS implementation. As a separate application, treenav can easily be integrated into existing, custom setups and does not enforce or require users to use a particular content management system.

Sharing the same principles, django-pagelets integrates seamlessly with treenav and can be used together to create a flexible CMS product.

For complete documentation checkout,


  • Generic functionality with multiple URL specifications: get_absolute_url(), reverse(), or raw URLs
  • Packaged with templates to render the tree hierarchy with nested <ul>'s, but can easily be overridden with custom templates
  • Easily customize each item's template or fall back to a default menuitem.html
  • Useful CSS classes for flexible UI customization
  • Automatically sets "active" on item and item's parents if PATH_INFO is equal to item.href
  • Efficient: minimizes database access with django-mptt functionality
  • Caches the tree so that repeated page views do not hit the database.
  • Simple links in the MenuItem list view for refreshing the cache and href from the database.


Using the demo

For a quick demo, follow these steps:

  1. Create a virtualenv. (This example uses mkvirtualenv, but there are many other ways to do it):

    $ mkvirtualenv django-treenav
  2. Check out the code and install the requirements:

    (django-treenav)$ git clone git://
    (django-treenav)$ cd django-treenav/
    (django-treenav)~/django-treenav/$ pip install -Ur dev-requirements.txt
  3. Run migrations and create a superuser so you can login to the Django admin:

    (django-treenav)~/django-treenav$ python migrate
    (django-treenav)~/django-treenav$ python createsuperuser
  4. Run the server:

    (django-treenav)~/django-treenav$ python runserver
  5. Visit http://localhost:8000/ in your browser and follow the instructions.


  1. Install the app with pip:

    pip install django-treenav
  2. Add to your INSTALLED_APPS and run migrate:

  3. Include these context processors:

        'OPTIONS': {
          'context_processors': [
  4. Add these urls:

    urlpatterns = [
        url(r'^treenav/', include('treenav.urls')),

Maintainer Information

We use Github Actions to lint (using pre-commit, black, isort, and flake8), test (using tox and tox-gh-actions), calculate coverage (using coverage), and build documentation (using sphinx).

We have a local script to do these actions locally, named

$ ./

A Github Action workflow also builds and pushes a new package to PyPI whenever a new Release is created in Github. This uses a project-specific PyPI token, as described in the PyPI documentation here. That token has been saved in the PYPI_PASSWORD settings for this repo, but has not been saved anywhere else so if it is needed for any reason, the current one should be deleted and a new one generated.

As always, be sure to bump the version in treenav/ before creating a Release, so that the proper version gets pushed to PyPI.

Development sponsored by Caktus Consulting Group, LLC.


Extensible, hierarchical, and pluggable navigation system for Django sites







No packages published