{"id":8947,"library":"django-filer","title":"django-filer","description":"django-filer is an active file management application for Django that simplifies handling of files and images within Django projects. It provides a robust file browser and model fields for seamless integration. The current version is 3.4.4, and the library maintains an active release cadence with frequent updates and patches.","status":"active","version":"3.4.4","language":"en","source_language":"en","source_url":"https://github.com/django-cms/django-filer","tags":["Django","file management","image management","CMS","media"],"install":[{"cmd":"pip install django-filer","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Core framework dependency. Supports Django >= 3.2, 4.2, 5.0, 5.1, 5.2.","package":"Django"},{"reason":"Required for versions < 3.0 for tree structure. Dropped in 3.0.","package":"django-mptt"},{"reason":"Used for efficient thumbnail generation and image processing.","package":"easy_thumbnails"},{"reason":"Used for polymorphic models within filer.","package":"django-polymorphic"},{"reason":"Image processing library (recommended over PIL). Not a direct pip dependency due to historical installation issues, but functionally required for image features.","package":"Pillow","optional":true}],"imports":[{"symbol":"FilerImageField","correct":"from filer.fields.image import FilerImageField"},{"symbol":"FilerFileField","correct":"from filer.fields.file import FilerFileField"},{"symbol":"Folder","correct":"from filer.models.foldermodels import Folder"}],"quickstart":{"code":"# settings.py\nINSTALLED_APPS = [\n    # ... other apps\n    'django.contrib.admin',\n    'django.contrib.auth',\n    'django.contrib.contenttypes',\n    'django.contrib.sessions',\n    'django.contrib.messages',\n    'django.contrib.staticfiles',\n    'mptt', # Required by easy_thumbnails/polymorphic if not Django-Filer 3.0+\n    'easy_thumbnails',\n    'filer',\n    'polymorphic',\n]\n\nMEDIA_ROOT = os.path.join(BASE_DIR, 'media')\nMEDIA_URL = '/media/'\n\n# models.py\nfrom django.db import models\nfrom filer.fields.image import FilerImageField\nfrom filer.fields.file import FilerFileField\n\nclass Product(models.Model):\n    name = models.CharField(max_length=255)\n    image = FilerImageField(null=True, blank=True, on_delete=models.SET_NULL, related_name=\"product_images\")\n    brochure = FilerFileField(null=True, blank=True, on_delete=models.SET_NULL, related_name=\"product_brochures\")\n\n    def __str__(self):\n        return self.name\n","lang":"python","description":"To get started with django-filer, install the package, add `filer`, `easy_thumbnails`, `mptt`, and `polymorphic` (if not already present) to your `INSTALLED_APPS` in `settings.py`, and define `MEDIA_ROOT` and `MEDIA_URL`. Then, run migrations. You can then use `FilerImageField` or `FilerFileField` in your Django models, similar to Django's native `ImageField` and `FileField`. Remember to specify an `on_delete` parameter for these fields."},"warnings":[{"fix":"Run `python manage.py makemigrations filer` and `python manage.py migrate` after upgrading. Review `FILER_FILE_VALIDATORS` settings if you need to allow specific file types. Refer to official upgrade instructions.","message":"Upgrading from django-filer 2.x to 3.0 drops the dependency on django-mptt. This removes `level`, `lft`, `rght`, and `tree_id` fields from the `Folder` model. Existing data using these fields will need migration handling. Additionally, upload restrictions for HTML and SVG files were introduced.","severity":"breaking","affected_versions":"3.0.0+"},{"fix":"To explicitly allow binary files, add `FILER_REMOVE_FILE_VALIDATORS = ['application/octet-stream']` to your `settings.py`. Consider implementing virus scanning for uploaded files.","message":"From version 3.3.0, django-filer changed its security policy by default disallowing the upload of binary or unknown file types (e.g., `application/octet-stream`). This was a security measure to prevent malware distribution.","severity":"breaking","affected_versions":"3.3.0+"},{"fix":"Ensure that a standard, visible field (e.g., `CharField`) precedes any `FilerFileField` or `FilerImageField` in your admin `fieldsets` or `fields` configuration.","message":"Placing a `FilerFileField` or `FilerImageField` as the very first field in a Django admin form can cause JavaScript errors due to Django's admin trying to set focus on a hidden field.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Review your `FolderAdmin` customizations if you encounter unexpected sorting. You might need to override `get_ordering` or similar methods, or contribute to `django-filer` to address the underlying issue.","message":"Sorting logic for files in directory listings was reported to be inconsistent or broken in `3.0.x` versions compared to `2.2.x`, particularly regarding files with and without explicit names.","severity":"gotcha","affected_versions":"3.0.x"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Ensure `pip install django-filer` is run, and add `'filer'`, `'easy_thumbnails'`, `'mptt'`, and `'polymorphic'` to your `INSTALLED_APPS` in `settings.py`.","cause":"The 'filer' app is not correctly added to INSTALLED_APPS in settings.py, or the package is not installed.","error":"ModuleNotFoundError: No module named 'filer'"},{"fix":"After upgrading `django-filer` to 3.x, run `python manage.py makemigrations filer` and then `python manage.py migrate`. This will apply the necessary database schema changes that remove these fields.","cause":"This error typically occurs when migrating from `django-filer` 2.x to 3.x, where the dependency on `django-mptt` and its associated fields (`level`, `lft`, `rght`, `tree_id`) were removed from the `Folder` model in 3.0.","error":"django.db.utils.ProgrammingError: column filer_folder.tree_id does not exist"},{"fix":"When defining `FilerImageField` or `FilerFileField` in your models, always include an `on_delete` argument, e.g., `on_delete=models.CASCADE`, `on_delete=models.SET_NULL` (if `null=True`), or `on_delete=models.PROTECT`.","cause":"Similar to Django's built-in `ForeignKey`, `FilerImageField` and `FilerFileField` require an `on_delete` parameter in modern Django versions.","error":"django.core.exceptions.FieldError: 'FilerImageField' has no 'on_delete' specified and isn't null."},{"fix":"If you need to allow such file types, add `FILER_REMOVE_FILE_VALIDATORS = ['application/octet-stream']` to your `settings.py`. For stricter control, you can define custom validators via `FILER_FILE_VALIDATORS`.","cause":"Since `django-filer 3.3`, binary or unknown file types are blocked by default for security reasons. `application/octet-stream` is a common type for unclassified binary files.","error":"Files of type 'application/octet-stream' are not allowed"}]}