---
id: django-cleanup
version: "9.0.0"
license: unclear
license_treatment: permissive
maintenance: aging
---

# django-cleanup — Deletes old files.

License: permissive · Maintenance: aging · Downloads: 702.4K/mo

## 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 above — 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

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

- License: not declared (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: aging
- Downloads: 702.4K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

django file cleanup, automatic file deletion django, orphaned file removal, filefield cleanup, django storage management, imagefield auto delete, django file housekeeping, django-app, file-management, signal-based

[View on SkillFed](https://skillfed.io/packages/django-cleanup) · [View on PyPI](https://pypi.org/project/django-cleanup/)