django-cleanup

Warnings

• gotcha The `django_cleanup.apps.CleanupConfig` must be placed *last* in your `INSTALLED_APPS` setting. This ensures that it can correctly discover all `FileField`s across all your applications and that file deletion integrity within transactions is maintained, even if other apps' signal handlers raise exceptions.
  Fix: Ensure 'django_cleanup.apps.CleanupConfig' is the last entry in `INSTALLED_APPS` in your `settings.py`.
• gotcha If your project uses a database that does not support transactions, or if a transaction rolls back, files *may* be lost without their corresponding model instance being fully deleted or updated. While `django-cleanup` mitigates this using `post_save` and `post_delete` signals, it's a known limitation to be aware of if your database setup is unusual.
  Fix: Use a transactional database. If not possible, ensure robust backup strategies and understand the implications of rollbacks on file integrity. Consider alternative manual cleanup solutions if this is a critical concern.
• gotcha `django-cleanup` relies on Django's application registry to discover models and their `FileField`s. If your models are not properly loaded (e.g., if they are not defined or imported in your app's `models.py` or `models/__init__.py`), `django-cleanup` may not be able to discover them and thus won't remove files as expected.
  Fix: Ensure all models within your Django apps are correctly defined or imported within their respective `models.py` or `models/__init__.py` files to guarantee they are registered with Django's ORM.
• gotcha Files that are explicitly set as a `FileField`'s `default` value will *not* be deleted by `django-cleanup`. This is by design to prevent accidental deletion of common default files that might be referenced by many instances.
  Fix: Be aware that default files are not managed. If a file associated with a `FileField` needs to be cleaned up, it should not be set as the field's `default`.

Install

• pip install django-cleanup Install via pip

Imports

• django_cleanup

  INSTALLED_APPS = ['...', 'django_cleanup']

  Primary configuration is via settings.py. For versions 8.x and earlier, 'django_cleanup' was sufficient. For 9.0.0 and later, it is recommended to use 'django_cleanup.apps.CleanupConfig'.
• CleanupConfig

  INSTALLED_APPS = ['...', 'django_cleanup.apps.CleanupConfig']

  While 'django_cleanup' still works, explicit use of CleanupConfig is generally recommended for application configuration classes in modern Django. The GitHub README for v9.0.0 explicitly shows 'django_cleanup.apps.CleanupConfig'.
• cleanup_pre_delete, cleanup_post_delete

  from django_cleanup.signals import cleanup_pre_delete, cleanup_post_delete

  Signals can be imported for custom interactions before or after a file is deleted by django-cleanup.

Quickstart

After installation, add `django_cleanup.apps.CleanupConfig` to your `INSTALLED_APPS`. `django-cleanup` will then automatically handle file deletion for any `FileField` or `ImageField` on your models when a model instance is deleted, or when a file in a field is replaced. No additional code is needed in your models or views for basic functionality.

import os
import django
from django.conf import settings
from django.db import models

os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'myproject.settings')

# Minimal Django settings for demonstration
if not settings.configured:
    settings.configure(
        INSTALLED_APPS=[
            'django.contrib.auth',
            'django.contrib.contenttypes',
            'django_cleanup.apps.CleanupConfig',
            'myapp' # Your app where models reside
        ],
        DATABASES={'default': {'ENGINE': 'django.db.backends.sqlite3', 'NAME': ':memory:'}},
        MEDIA_ROOT=os.path.join(os.getcwd(), 'media_test'),
        DEFAULT_AUTO_FIELD='django.db.models.AutoField',
    )
django.setup()

# Create a dummy app to hold models
class MyAppConfig(django.apps.AppConfig):
    name = 'myapp'
    label = 'myapp'

# Add dummy app to apps registry
if not django.apps.apps.get_app_config('myapp'):
    django.apps.apps.populate(settings.INSTALLED_APPS)

# Define a simple model with a FileField
class MyModel(models.Model):
    name = models.CharField(max_length=100)
    image = models.ImageField(upload_to='images')

    def __str__(self):
        return self.name

# Ensure media directory exists for testing
os.makedirs(settings.MEDIA_ROOT, exist_ok=True)

# Simulate model usage
print(f"Media root: {settings.MEDIA_ROOT}")

# 1. Create instance and save a dummy file
instance = MyModel(name='Test Item')
# Create a dummy image file
dummy_image_path = os.path.join(settings.MEDIA_ROOT, 'images', 'test_image.jpg')
os.makedirs(os.path.dirname(dummy_image_path), exist_ok=True)
with open(dummy_image_path, 'w') as f:
    f.write('dummy image content')

instance.image.name = 'images/test_image.jpg'
instance.save()
print(f"File exists after creation: {os.path.exists(dummy_image_path)}")

# 2. Update instance with a new file (old one should be deleted)
new_dummy_image_path = os.path.join(settings.MEDIA_ROOT, 'images', 'new_test_image.jpg')
with open(new_dummy_image_path, 'w') as f:
    f.write('new dummy image content')

old_image_name = instance.image.name
instance.image.name = 'images/new_test_image.jpg'
instance.save()

print(f"Old file '{old_image_name}' exists after update: {os.path.exists(os.path.join(settings.MEDIA_ROOT, old_image_name))}")
print(f"New file exists after update: {os.path.exists(new_dummy_image_path)}")

# 3. Delete instance (associated file should be deleted)
instance_pk = instance.pk
instance.delete()

print(f"New file exists after instance deletion: {os.path.exists(new_dummy_image_path)}")

# Clean up test media directory (optional)
import shutil
shutil.rmtree(settings.MEDIA_ROOT)
print("Cleaned up media_test directory.")