- Adminita is a theme for the Django admin. You install it with pip and your admin changes look. Nothing else about it changes.
- It needs Python 3.10 or newer and Django 5.2 or 6.0. Django 6.0 needs Python 3.12 or newer.
- The one rule that matters: "adminita" goes first in INSTALLED_APPS, above django.contrib.admin.
- After any install or upgrade, run collectstatic. Most "it did not work" problems are fixed by that command.
- Dark mode and form autosave work straight away. There is nothing to switch on.
- Adminita is open source (MIT). CONTRIBUTING.md on GitHub explains how to report a problem or send a change.
This guide takes you from an existing Django project to a themed admin. Allow about fifteen minutes. Tick off each step as you go: your progress is saved in this browser.
Before you start
You need a working Django project that already opens at /admin/, and these versions:
| Item | Version |
|---|---|
| Python | 3.10 or newer (3.12 or newer if you use Django 6.0) |
| Django | 5.2 or 6.0 |
| Node.js and npm | Only if you want to change the theme shades. Not needed to use Adminita. |
Adminita 0.2.1 needs Django 5.2 or newer. If your project is on an older Django, upgrade Django first, or stay on Adminita 0.2.0, which no longer gets updates.
Install and set up Adminita
These five steps are all most projects need.
Add Adminita to your project
- Install the packageRun this in the terminal, with your project's virtual environment switched on.
Show the command
pip install adminita - Add it to INSTALLED_APPS, first in the listOpen settings.py. Adminita has to sit above django.contrib.admin so its templates are found first.
Show the setting
INSTALLED_APPS = [
"adminita", # first, above the admin
"django.contrib.admin",
"django.contrib.auth",
"django.contrib.contenttypes",
"django.contrib.sessions",
"django.contrib.messages",
"django.contrib.staticfiles",
# your own apps
] - Check your static file settingsAdminita ships its own CSS and JavaScript, so Django needs to know where static files live.
Show the setting
STATIC_URL = "/static/"
STATIC_ROOT = BASE_DIR / "staticfiles" - Set your admin site namesIn your project's urls.py, add three lines. They change the header, the browser tab and the heading on the admin home page.
Show the code
from django.contrib import admin
admin.site.site_header = "Your Site Name"
admin.site.site_title = "Your Site Title"
admin.site.index_title = "Welcome to Your Site" - Collect the static filesThis copies the Adminita files to where Django serves them from.
Show the command
python manage.py collectstatic --noinput
Run it and log in
If your project has no database or admin user yet, create them first. Skip these two commands if you already have both.
python manage.py migrate python manage.py createsuperuser
Then start the server and open http://localhost:8000/admin/ in your browser.
python manage.py runserver
Log in with your admin user. You should see the new sidebar, the new login page and the same models you had before.
Want to see it before you install it? The live demo is running Adminita now, with a demo login on the page.
Your admin looks the same as before? Almost always the cause is the order of INSTALLED_APPS, or collectstatic has not been run. Check both before looking anywhere else.
Your first look around
Work through this list the first time you open the themed admin.
Your first five minutes
- Log in at /admin/Use the superuser you already have, or the one you just created.
- Check your site namesThe header, the tab title and the home heading should show your own words.
- Try the dark mode toggleIt follows your device setting until you click the toggle once. After that it remembers your choice.
- Make the window narrowThe sidebar folds away on small screens.
- Open any record and start editingThe change form and the list pages work as they always did.
Form autosave
While you edit a form, Adminita keeps a copy of your unsaved changes in your browser. If you refresh the page or close the tab by accident, the form shows a banner when you come back, with two choices: Restore brings your changes back, and Discard throws the saved copy away.
The prompt never overwrites a record that was saved more recently than the draft. Nothing is sent to a server, because the draft lives only in your own browser.
Two helpers for your own admin classes
Adminita includes two small classes for common admin jobs. You import both from adminita.utils.
AlwaysVisibleAdmin
- Keeps a model listed on the admin home page, even if its list page redirects or adding is turned off
- Viewing and editing still follow normal permissions
SingletonAdmin
- For a model that only ever has one record, such as site settings
- The list page opens that one record directly
- Adding is blocked once the record exists, and deleting is turned off
To use one, make your admin class inherit from it instead of ModelAdmin. This example uses a site settings model:
from django.contrib import admin
from adminita.utils import SingletonAdmin
from .models import SiteSettings
@admin.register(SiteSettings)
class SiteSettingsAdmin(SingletonAdmin):
list_display = ("site_name",)If you have your own admin templates
Extend admin/base.html as you normally would. Do not add an adminita/ prefix. Django finds the Adminita templates by itself because the app is in INSTALLED_APPS.
Upgrading Adminita
Upgrade to 0.2.1
- Check your Django versionVersion 0.2.1 needs Django 5.2 or newer.
How do I check?
python -m django --version - Upgrade the packageOne command, in your project's virtual environment.
Show the command
pip install --upgrade adminita - Collect the static files againThis puts the new CSS and JavaScript in place.
Show the command
python manage.py collectstatic --noinput
You do not need to change your templates or settings for 0.2.1. Coming from a 0.1 release? Two extra things apply:
- If your TEMPLATES setting lists adminita.context_processors.admin_app_list, remove that line. It now only causes a warning.
- Staff users who are not superusers need view and change permission on any model that uses AlwaysVisibleAdmin or SingletonAdmin, or they will not see it. Superusers are not affected.
Changing the theme shades
You only need this section if you want your own shades. Adminita works fully without it. Changing them means building the CSS yourself, so you need the source code from GitHub and Node.js.
- Edit the shadesOpen adminita/static/src/input.css and change the values in the @theme block. It holds the primary shades (50 to 950) and the neutral shades (50 to 900).
- Build the CSSFrom the Adminita folder, run npm install once, then npm run build.
- Collect the static filesIn your project, run collectstatic --noinput again.
Trying the demo project
The GitHub repository includes a demo project, so you can run Adminita without touching your own site. Clone the repository, install the requirements, install the package in editable mode, then run migrate and createsuperuser. Version 0.2.1 made this work on a clean machine.
The demo can read DEBUG and ALLOWED_HOSTS from a .env file. A .env.example file is included as a template. The .env file is optional: without it the demo runs for local use only.
Troubleshooting
The admin looks the same as before
Check that "adminita" is the first entry in INSTALLED_APPS, above django.contrib.admin. Then run collectstatic again and refresh the page with Ctrl and F5 together.
The page has no styling at all
Static files are not being found. Check STATIC_URL and STATIC_ROOT, run collectstatic, and on a live server make sure your web server serves the static folder.
The styles are out of date after an upgrade or a shade change
If you changed the shades, run npm run build first. Either way, run collectstatic, then refresh with Ctrl and F5.
I get errors on an older Django
Adminita 0.2.1 needs Django 5.2 or newer. Upgrade Django, or stay on Adminita 0.2.0.
A deprecation warning mentions admin_app_list
Remove adminita.context_processors.admin_app_list from the TEMPLATES setting. It is no longer needed.
My staff users cannot see a model that superusers can
Give those users view and change permission on the model. This applies to models that use AlwaysVisibleAdmin or SingletonAdmin.
How well does it work on a phone?
The sidebar folds away and most pages work well. Wide tables scroll sideways, tabular inlines are cramped, and rich text editors and date pickers may not behave well on small screens.
Report a problem or help improve it
Adminita is open source under the MIT terms, so you are free to use it, change it and share it. The CONTRIBUTING.md file on GitHub explains how to set up a working copy, how to open an issue, and how to send a change. When you report a bug, include your Django and Python versions, your browser and the steps to repeat it. The file also lists ideas for new contributors, such as mobile testing, accessibility improvements and new themes.
- Install with pip install adminita, put "adminita" first in INSTALLED_APPS, set your site names and run collectstatic.
- Open /admin/ and your admin has the new look, dark mode and form autosave.
- Use AlwaysVisibleAdmin and SingletonAdmin from adminita.utils for models that need them.
- To upgrade, run pip install --upgrade adminita, then collectstatic. Version 0.2.1 needs Django 5.2 or newer.
- If it does not look right, check the order of INSTALLED_APPS and run collectstatic again.
This page was built with Interactive Content Blocks
The stats bar, guide trackers and checklist on this page come from Interactive Content Blocks, a set of seven ready-made blocks for your own pages. Ticks and progress are saved in the reader's own browser. The set includes an AI skill file, so any AI assistant can add the blocks for you.
See Interactive Content Blocks →