Faceted filtering of Django querysets.
Switch branches/tags
Nothing to show
Clone or download
Type Name Latest commit message Commit time
Failed to load latest commit information.
docs slowly expanding docs further Jun 4, 2012
requirements use travis-ci, skip broken test, fix multiprocessing error and add fl… May 18, 2012
tests back out attempts to support django 1.2, as there were no generic cla… May 19, 2012
.gitignore initial import of ported and merged code May 17, 2012
.travis.yml updating travis.yml to exclude python 2.5 and django 1.5 test run Dec 31, 2012
AUTHORS.rst begin overhaul of the documentation May 22, 2012
CHANGES.rst update version and code for new development work May 19, 2012
LICENSE.txt backport django/python test tools for 2.5/2.6 testing on travis-ci May 18, 2012
MANIFEST.in initial import of ported and merged code May 17, 2012
README.rst more doc expansion May 23, 2012
runtests.py use travis-ci, skip broken test, fix multiprocessing error and add fl… May 18, 2012
setup.py begin overhaul of the documentation May 22, 2012


django-refinery ci-status

Allows users to filter down a queryset based on a model's fields, similar to the Django admin's list_filter interface. A FilterTool helper class is provided, which will (by default) map filters to model fields and create a form for queryset manipulation. The helper class interface will feel familiar to anyone who's used a Django ModelForm.

Author:Jacob Radford

Example usage

Given a Product model you could create a FilterTool for it with:

import refinery

class ProductFilterTool(refinery.FilterTool):
    class Meta:
        model = Product
        fields = ['name', 'price']

And then in your view you could do:

def product_list(request):
    filtertool = ProductFilterTool(request.GET or None)
    return render_to_response('product/product_list.html',
        {'filtertool': filtertool})

And then in your template:

<form action="" method="get">
    {{ filtertool.form.as_p }}
    <input type="submit" />
  {% for obj in filtertool %}
      <li>{{ obj.name }} - ${{ obj.price }}</li>
  {% endfor %}

For more complex usage or custom needs, refer to the project documentation.


  • Python 2.5+
  • Django 1.3+


  • pip install -U django-refinery
  • Add refinery to your INSTALLED_APPS

To install the in-development version of django-refinery, run pip install django-refinery==dev.


See the docs folder or read it on readthedocs for expanded information on:

  • Usage examples
  • Contributing
  • Integration with other apps
  • Project background
  • Low-level API
  • Creating custom filters


If you want to help out with the development of django-refinery, by posting detailed bug reports, proposing new features, or suggesting documentation improvements, use the issue tracker. If you want to fix it yourself, thank you! Fork the project, make changes and send a pull request. Please do create an issue to discuss your plans.


Django-refinery is based on django-filter, an application created by Alex Gaynor. For a complete project history and list of contributors, see the project documentation.


  • Overhaul and expand documentation
  • Overhaul and expand test suite
  • Refactor generic class view (look into pagination of ListView)
  • Allow integration of django-floppyforms
  • Allow integration of django-crispy-forms
  • Allow filters on non-required fields with choices to provide option of filtering the records that are unset. (i.e. FK is null)
  • Allow abstraction of ordering values used to avoid passing internal information in GET params (i.e. user__username)
  • Look into adapting LinkWidget and overall behavior to support filtering like django-easyfilters or maybe drop the widget?
  • Allow multiple ordering fields to be used at the same time