Quick start guide

Before installing django-admin-tools, you’ll need to have a copy of Django already installed. For the 0.8 release, Django 1.7 or newer is required.

Note

Important note to users of django 1.6 or below: starting from 0.6.0, django-admin-tools is NOT compatible with django <= 1.6. If you want, you can still use the 0.5.2 version that will always be available on Pypi.

Installing django-admin-tools

django-admin-tools requires Django version 1.3 or superior, optionally, if you want to display feed modules, you’ll also need the Universal Feed Parser module.

There are several ways to install django-admin-tools, this is explained in the installation section.

For the impatient, the easiest method is to install django-admin-tools via easy_install or pip.

Using easy_install, type:

easy_install -Z django-admin-tools

Note that the -Z flag is required, to tell easy_install not to create a zipped package; zipped packages prevent certain features of Django from working properly.

Using pip, type:

pip install django-admin-tools

Basic configuration

For a more detailed guide on how to configure django-admin-tools, please consult the configuration section.

Prerequisite

In order to use django-admin-tools you obviously need to have configured your Django admin site. If you didn’t, please refer to the relevant django documentation.

Configuration

First make sure you have the django.core.context_processors.request template context processor in your TEMPLATE_CONTEXT_PROCESSORS or TEMPLATES settings variable

Then add the admin_tools.template_loaders.Loader template loader to your TEMPLATE_LOADERS or TEMPLATES settings variable.

Note

Starting from django 1.8, TEMPLATE_CONTEXT_PROCESSORS and TEMPLATE_LOADERS are deprecated, they are replaced by the TEMPLATES variable, please refer to the relevant django documentation.

Note

Windows users: due to filename restrictions on windows platforms, you have to put the admin_tools.template_loaders.Loader at the very begining of the list in your TEMPLATES or TEMPLATE_LOADERS settings variable.

Then, add admin_tools and its modules to the INSTALLED_APPS like this:

INSTALLED_APPS = (
    'admin_tools',
    'admin_tools.theming',
    'admin_tools.menu',
    'admin_tools.dashboard',
    'django.contrib.auth',
    'django.contrib.sites',
    'django.contrib.admin'
    # ...other installed applications...
)

Important

it is very important that you put the admin_tools modules before the django.contrib.admin module, because django-admin-tools overrides the default Django admin templates, and this will not work otherwise.

Then, just add django-admin-tools to your urls.py file:

urlpatterns = patterns('',
    url(r'^admin_tools/', include('admin_tools.urls')),
    #...other url patterns...
)

Finally simply run:

python manage.py migrate

To collect static files run:

python manage.py collectstatic

Important

it is very important that django.contrib.staticfiles.finders.AppDirectoriesFinder be there in your STATICFILES_FINDERS.

Testing your new shiny admin interface

Congrats! At this point you should have a working installation of django-admin-tools. Now you can just login to your admin site and see what changed.

django-admin-tools is fully customizable, but this is out of the scope of this quickstart. To learn how to customize django-admin-tools modules please read the customization section.