Registry / web-framework / django-watchman

django-watchman

library1.5.0pypypi✓ verified 87d ago

django-watchman exposes a status endpoint for your backing services like databases, caches, and other services. It is currently at version 1.5.0 and maintains an active release cadence with regular updates and security fixes.

web-framework database observability

pip install django-watchman

github ↗package ↗docs ↗changelog ↗

INSTALL

IMPORT

SIG · DJANGO-WATCHMAN

django-watchman

web-frameworkpythonv1.5.0

Install

3.4s avg

Import

629ms

Disk

66MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.5.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.920 runs

installs and imports cleanly · install 0.0s · import 0.663s · 66.4MB

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 3.4s · import 0.595s · 67MB

66MB installed

● package 66MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

watchman

✓ import watchman

✗ from django.urls import re_path, include

To quickly integrate `django-watchman`, add 'watchman' to your `INSTALLED_APPS` and include `watchman.urls` in your project's `urls.py`. This will provide a JSON status endpoint at `/watchman/` and an HTML dashboard at `/watchman/dashboard/`. For a simpler liveness probe, the `/watchman/ping/` endpoint is also available.

import os # settings.py INSTALLED_APPS = [ # ... other apps 'watchman', ] # urls.py from django.urls import re_path, include urlpatterns = [ # ... other url patterns re_path(r'^watchman/', include('watchman.urls')), # For a minimal status endpoint (optional) # from watchman.views import bare_status # re_path(r'^watchman/bare/$', bare_status), ] # Optional: Protect with a token (add to settings.py) # WATCHMAN_TOKEN = os.environ.get('WATCHMAN_TOKEN', 'your_secret_token') # Run checks from command line (optional) # python manage.py watchman -v 2

Debug

Known issues

breakingVersion 1.0.0 dropped support for Python 2 and Django versions older than 2.0. Additionally, it removed the dependency on `django-jsonview` in favor of Django's built-in `JsonResponse`.

fix

Upgrade your Python environment to 3.10+ and Django to 2.0+ (preferably 4.2+), and remove `django-jsonview` from your dependencies if upgrading from pre-1.0.0 versions.

affects: <1.0.0

deprecatedPrior to version 1.3.0, `django-watchman` used `django.conf.urls.url()`. This function has been deprecated in modern Django versions (3.1+), which now primarily use `re_path()` or `path()`.

fix

Ensure your `urls.py` uses `re_path(r'^watchman/', include('watchman.urls'))` for compatibility with Django 3.1+.

affects: <1.3.0

gotchaWhen configuring `WATCHMAN_CHECKS` in your settings, ensure it is a sequence (e.g., a list or a tuple), not a single string. For a tuple with one item, remember the trailing comma: `('my.custom.check',)`.

fix

If you encounter `TypeError: 'str' object is not iterable` or `ImportError` related to `WATCHMAN_CHECKS`, change your setting from `WATCHMAN_CHECKS = 'single.check'` to `WATCHMAN_CHECKS = ('single.check',)` or `WATCHMAN_CHECKS = ['single.check']`.

affects: >=1.0.0

gotchaThe database health check in `django-watchman` might fail for Oracle databases when using `SELECT 1` without a `FROM` clause.

fix

Upgrade to `django-watchman` 1.5.0 or newer, which addresses this by using `SELECT 1 FROM DUAL` for Oracle.

affects: <1.5.0

gotchaVersion 1.4.0 included a security fix for a Regular Expression Denial of Service (ReDoS) vulnerability in the Authorization header parsing. Crafted input could lead to polynomial backtracking.

fix

Upgrade to `django-watchman` 1.4.0 or newer to mitigate the ReDoS vulnerability.

affects: <1.4.0

Upgrade

Version history

1.5.0latest on PyPI · released Mar 8, 2026

Audit

Dependencies

DjangorequiredAs a Django pluggable application, it requires Django to function. Supports Django 4.2, 5.1, and 5.2.

PythonrequiredRequires Python >=3.10.

Agent activity

21 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/mwarkentin/django-watchman ↗

packagehttps://pypi.org/project/django-watchman/ ↗

docshttps://django-watchman.readthedocs.io ↗

changeloghttps://github.com/mwarkentin/django-watchman/blob/main/CHANGELOG.md ↗