This package can be views a Django package which tries to fully utilize jQuery File Upload, with minimal customization. Beside that, some of the ideas/code are inspired by Django-jfu and Django-files-widget.


  • Q: Why there isn’t a delete view for image in the widget?

  • A: Image upload behavior is much more complex than generic form views. Actually, the jQuery File Upload has a working delete button, but we changed it to an UI behavior of remove an instance from the gallery (no physical deletion), considered the following situations:

    • For the simplest case, when a user navigate away before saving the gallery they have just uploaded, it’s almost impossible to delete those images from client side.

    • Another situations happens when a gallery field is a required field. If there exists a delete view for the image instance, when a user tries to delete ALL the images he/she had previously saved, from the UI, and then he/she submit the form. Undoubtedly, the form will raise an invalid error, and the GalleryField of the gallery instance won’t get updated. However, since all the image instances have been deleted before form submission, the form will then display broken images after reloading.

    • When an image presents in different galleries/albums, deletion of the image from one gallery will make it a broken image when view other galleries which contain it.

    To avoid such situations, our suggestion is not to provide a delete view, but a strategy to identify orphaned image model instances, and delete them with a cron task: create an M2M relationship between the image models and the gallery models. Through post-save signals of the gallery model, we are able to update the M2M relationship between all image model instances and related gallery model instances. In this way, image model instances which were not involved in any M2M relationship can be identified as orphaned images, the deletion of which are accurate and easy. The demo_custom.receivers might provide a feasible solution for the issue. Other suggestions are also appreciated.


  • More detailed Documentation

Known issues

  • Currently, it’s hard (although not impossible) to use the widget in a Non-model formfield.

  • CSS rendering of buttons in Admin.

  • Does not support .svg because django ImageField can’t handle SVG images (Django #14092).

  • Does not support cropping .gif (cropperjs #756).

  • Does not support previewing and cropping .tiff (jQuery-File-Upload #1576, cropperjs #622).


Released under the MIT license.