django-cleanup

What it is and what it does

django-cleanup is a Django app that automatically manages file cleanup for FileField and ImageField instances. It hooks into Django's model signals (post_init, pre_save, post_save, post_delete) to track when files are replaced or models are deleted, then schedules file deletion within the current transaction. This prevents orphaned files from accumulating on disk when you update or remove model instances.

The package works transparently once installed—you add it to INSTALLED_APPS (at the bottom to avoid signal handler conflicts) and it discovers all FileField instances in your models. It maintains a local cache of original field values to detect changes, and integrates with Django's transaction system to ensure deletions happen safely. It includes advanced features like pre/post-delete signals for integrating with thumbnail libraries, a refresh method for cache management, and decorators to selectively ignore or include specific models.

Use it for:

• Remove old product images when updating an e-commerce catalog without leaving orphaned files on disk.
• Clean up user profile pictures when accounts are deleted or users upload new avatars.
• Prevent storage bloat in document management systems when old versions are replaced.
• Integrate with thumbnail libraries to delete generated thumbnails alongside original images.
• Ensure file consistency in multi-tenant applications where model deletions must not leave dangling file references.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Automatically deletes old files when Django FileField and ImageField values change or models are deleted, eliminating orphaned files from storage.

Yes. django-cleanup solves a common Django problem (orphaned files) with zero configuration beyond adding it to INSTALLED_APPS. No runtime dependencies, permissive license, and a stable codebase with 1213 GitHub stars make it a low-risk addition. The aging maintenance status is not a concern given the package's narrow, well-defined scope and recent commit activity. Install it unless your project uses a non-transactional database or shares files across multiple model instances (both documented limitations).

Install

django-cleanup on PyPI

pip install django-cleanup

uv add django-cleanup

poetry add django-cleanup

Installing django-cleanup

Before you install

Low friction install with no runtime dependencies. Maintenance status is aging—last release was 695 days ago—but the repository remains active with recent commits and no archived status, suggesting the package is stable rather than abandoned.

License in practice

MIT license (permissive) allows free use, modification, and distribution with minimal restrictions, making it safe to integrate into most projects without legal concern.

Quickstart

pip install django-cleanup

Add to settings.py INSTALLED_APPS:
INSTALLED_APPS = (
    ...,
    'django_cleanup.apps.CleanupConfig',
)

Must be placed at the bottom of INSTALLED_APPS to ensure signal handler integrity; models must be properly loaded in models.py or models/__init__.py for discovery to work.

Verify before relying

• Whether the package handles all file storage backends (S3, Azure, etc.) or only local filesystem storage.
• Performance impact when models have many FileField instances or bulk delete operations occur.
• Behavior with soft-delete patterns or custom deletion logic in model managers.

Package facts

Evidence: django_cleanup-9.0.0-py3-none-any.whl

Keywords: django

Tags

More Utilities packages