Django-blocklist

This is a Django app that implements IP-based blocklisting. Its BlocklistMiddleware performs the blocking, and its clean_blocklist management command deletes entries which have satisfied the cooldown period. Entries also have a reason field, used in reporting. There are utility functions to add/remove IPs, an admin, and several management commands.

This app is primarily for situations where server-level blocking is not available, e.g. on platform-as-a-service hosts like PythonAnywhere or Heroku. Being an application-layer solution, it's not as performant as blocking via firewall or web server process, but is suitable for moderate traffic sites. It also offers better integration with the application stack, for easier management.

Quick start

The PyPI package name is django-blocklist; add that to your requirements.txt or otherwise install it into your project's Python environment.
Add "django_blocklist" to settings.INSTALLED_APPS
Add "django_blocklist.middleware.BlocklistMiddleware" to settings.MIDDLEWARE
Run python manage.py migrate to create the django_blocklist_blockedip table.
Add IPs to the list (via management commands, utils.update_blocklist, or the admin).
Set up a cron job or equivalent to run manage.py clean_blocklist daily.

Management commands

Django-blocklist includes several management commands:

clean_blocklist — remove entries that have fulfilled their cooldown period
import_blocklist — convenience command for importing IPs from a file
print_blocklist — print list of blocked IPs in plain text or JSON form
remove_from_blocklist — remove one or more IPs
report_blocklist — information on the current entries (see the sample report)
search_blocklist — look for an IP in the list; in addition to info on stdout, returns an exit code of 0 if successful
update_blocklist — add/update IPs; --skip-existing prevents updating existing records

See --help for each of these for more details.

Configuration

You can customize the following settings via a BLOCKLIST_CONFIG dict in your project settings:

cooldown — Days to expire, for new entries; default 7
denial-template — For the denial response; an f-string with {ip} and {cooldown} placeholders

Utility methods

The utils module defines some convenience functions:

remove_from_blocklist(ip: str) — removes an entry, returning True if successful
should_block(request: HttpRequest) — Checks the request IP and method against the blocklist.
update_blocklist(ips: set, reason: str, cooldown: int, last_seen: datetime) — adds IPs to the blocklist (all args except ips are optional)

Development

Project hub: django-blocklist on Gitlab
Development is managed with Poetry
Quickstart: python -m venv venv; source venv/bin/activate; poetry install
The project's settings.py is minimal, just enough to run the tests and the admin
Run tests: tox in project root to run the full test matrix, or use pytest to run specific tests under your installed Django
Linting: ruff check django_blocklist
manage.py runserver lets you try out the admin
Merge requests and issues (tickets) are welcome!

Metadata

Release files for django-blocklist 3.2.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for django-blocklist 3.2.2
File	Size	Uploaded
django_blocklist-3.2.2.tar.gz	16.9 kB	Jul 15, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for django-blocklist 3.2.2
File	Interpreter	ABI	Platform	Reset
django_blocklist-3.2.2-py3-none-any.whl 27.3 kB Jul 15, 2026	Python 3	none	any	Details

Total release size: 44.2 kB

Release files / django_blocklist-3.2.2.tar.gz

Download URL	django_blocklist-3.2.2.tar.gz
Size	16.9 kB
Tags	Source
SHA-256 checksum How to use checksums	`5b54768361ad019e5affa2ce6931daad5f7446a1bebc11a4d8e982bf517517a2`
BLAKE2b-256 checksum How to use checksums	`bc4b95da477be612142c6cdafd4950247cb1470a87509fee81c1ae65739ca141`
Upload date	Jul 15, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`poetry/2.2.1 CPython/3.14.6 Darwin/25.5.0`

Release files / django_blocklist-3.2.2-py3-none-any.whl

Download URL	django_blocklist-3.2.2-py3-none-any.whl
Size	27.3 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`5cbfafbdb5f1e07afbbe0148764bbd266bade86d0113f9a6fe4ceb1842520e86`
BLAKE2b-256 checksum How to use checksums	`f1878aba055606c34c5bed2bd6e2ccf4e7f2e64b155992f0919c6208f237d70c`
Upload date	Jul 15, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`poetry/2.2.1 CPython/3.14.6 Darwin/25.5.0`