django-filer

3.4.4 · active · verified Thu Apr 16

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.

Common errors

```
ModuleNotFoundError: No module named 'filer'
```
cause The 'filer' app is not correctly added to INSTALLED_APPS in settings.py, or the package is not installed.

fix Ensure `pip install django-filer` is run, and add `'filer'`, `'easy_thumbnails'`, `'mptt'`, and `'polymorphic'` to your `INSTALLED_APPS` in `settings.py`.
```
django.db.utils.ProgrammingError: column filer_folder.tree_id does not exist
```
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.

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.
```
django.core.exceptions.FieldError: 'FilerImageField' has no 'on_delete' specified and isn't null.
```
cause Similar to Django's built-in `ForeignKey`, `FilerImageField` and `FilerFileField` require an `on_delete` parameter in modern Django versions.

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`.
```
Files of type 'application/octet-stream' are not allowed
```
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.

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`.

Warnings

breaking 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.
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.
breaking 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.
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.
gotcha 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.
Fix: Ensure that a standard, visible field (e.g., `CharField`) precedes any `FilerFileField` or `FilerImageField` in your admin `fieldsets` or `fields` configuration.
gotcha 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.
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.

Install

pip install django-filer Install latest version

Imports

FilerImageField

from filer.fields.image import FilerImageField

FilerFileField

from filer.fields.file import FilerFileField

Folder

from filer.models.foldermodels import Folder

Quickstart

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.

# settings.py
INSTALLED_APPS = [
    # ... other apps
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    'mptt', # Required by easy_thumbnails/polymorphic if not Django-Filer 3.0+
    'easy_thumbnails',
    'filer',
    'polymorphic',
]

MEDIA_ROOT = os.path.join(BASE_DIR, 'media')
MEDIA_URL = '/media/'

# models.py
from django.db import models
from filer.fields.image import FilerImageField
from filer.fields.file import FilerFileField

class Product(models.Model):
    name = models.CharField(max_length=255)
    image = FilerImageField(null=True, blank=True, on_delete=models.SET_NULL, related_name="product_images")
    brochure = FilerFileField(null=True, blank=True, on_delete=models.SET_NULL, related_name="product_brochures")

    def __str__(self):
        return self.name

view raw JSON →