cleanup_orphaned_photos

The cleanup_orphaned_photos command removes photo files that are no longer referenced in the database, freeing up storage space. This is useful after deleting items or during development when photo uploads fail.

How it works

The command scans photo directories and identifies files that:

Are not referenced in the collection_photo table
Are from incomplete form submissions (photos uploaded but item never created)
Are older than a specified threshold

Basic usage

python manage.py cleanup_orphaned_photos

Always use --dry-run first to preview what will be deleted.

Arguments and options

boolean

Preview mode - show what would be deleted without actually deleting files.Example:

python manage.py cleanup_orphaned_photos --dry-run

boolean

Show detailed output including each file being processed.Example:

python manage.py cleanup_orphaned_photos --verbose

boolean

Only clean up photos from incomplete form submissions (uploaded but never attached to an item).Example:

python manage.py cleanup_orphaned_photos --incomplete-only

integer

default:"24"

Only clean up photos older than specified hours (used with --incomplete-only).Example:

python manage.py cleanup_orphaned_photos --incomplete-only --older-than-hours 48

Cleanup modes

All orphaned photos

Removes all photo files not referenced in the database:

python manage.py cleanup_orphaned_photos --dry-run
python manage.py cleanup_orphaned_photos

What gets deleted:

Photos from deleted items
Manually deleted files that still exist on disk
Any file in item_photos/ or item_photos_avif/ without a database reference

Incomplete submissions only

Removes photos from failed form submissions (safer option):

python manage.py cleanup_orphaned_photos --incomplete-only --older-than-hours 24

What gets deleted:

Photos uploaded during item creation but never attached to an item
Photo records with content_type_id IS NULL
Only photos older than the specified threshold (default: 24 hours)

Example workflows

Safe cleanup (recommended)

Preview changes

python manage.py cleanup_orphaned_photos --dry-run --verbose

Review output

Check the list of files to be deleted and verify they’re safe to remove.

Run cleanup

python manage.py cleanup_orphaned_photos

Aggressive cleanup

Remove all incomplete photos older than 1 week:

python manage.py cleanup_orphaned_photos --incomplete-only --older-than-hours 168 --verbose

Production deployment

Run weekly via cron or Celery Beat:

# Crontab entry
0 2 * * 0 cd /var/www/footycollect && venv/bin/python manage.py cleanup_orphaned_photos --incomplete-only

Output example

Starting orphaned photo cleanup...
Found 245 files referenced in database
Found 12 orphaned files

Orphaned files:
  /media/item_photos/temp_abc123.jpg (245678 bytes)
  /media/item_photos_avif/temp_abc123.avif (89234 bytes)
  /media/item_photos/deleted_item_xyz.jpg (512000 bytes)
  ...

Deleted 12 files (1847912 bytes)

Automatic cleanup

FootyCollect includes automatic cleanup via Celery Beat periodic tasks:

Incomplete photos - Every 6 hours (photos from failed submissions)
All orphaned photos - Every 7 days (comprehensive cleanup)

Configure these tasks with:

python manage.py setup_beat_schedule

See setup_beat_schedule for details.

Storage directories

The command scans these directories:

MEDIA_ROOT/item_photos/ - Original uploaded photos
MEDIA_ROOT/item_photos_avif/ - AVIF-optimized versions

Database cleanup

When using --incomplete-only, the command also deletes orphaned database records:

DELETE FROM collection_photo 
WHERE uploaded_at < :cutoff_time 
AND content_type_id IS NULL

Troubleshooting

Permission denied

Ensure the user running the command has write permissions on the media directory:

sudo chown -R www-data:www-data /var/www/footycollect/media

Files still present after cleanup

Check if files are in use by another process or if the storage backend is remote (S3/R2).For remote storage, files are not automatically deleted from the bucket. Use the cloud provider’s lifecycle policies instead.

Database records without files

If photos are referenced in the database but files are missing, use:

python manage.py shell
from footycollect.collection.models import Photo
Photo.objects.filter(image__isnull=False).count()

Then investigate missing files in logs.

Photo Management

Learn about photo optimization and storage

Celery Tasks

Background tasks including automatic cleanup

​How it works

​Basic usage

​Arguments and options

​Cleanup modes

​All orphaned photos

​Incomplete submissions only

​Example workflows

​Safe cleanup (recommended)

​Aggressive cleanup

​Production deployment

​Output example

​Automatic cleanup

​Storage directories

​Database cleanup

​Troubleshooting

​Related

Photo Management

Celery Tasks

How it works

Basic usage

Arguments and options

Cleanup modes

All orphaned photos

Incomplete submissions only

Example workflows

Safe cleanup (recommended)

Aggressive cleanup

Production deployment

Output example

Automatic cleanup

Storage directories

Database cleanup

Troubleshooting

Related