django-hitcount: simple app to count hits/views for an object

django-hitcount: a simply django application that allows you to count hits/views on a per object basis. This app came about as an answer to my own question at Am hoping that others will find it useful.

March 2011 Update: I haven’t done much with this in the past few months and there are some good changes/forks out there that need to be merged. Sorry for the delays. I intend to update it in April when I finally have some free time to work on it again. Thanks for all your input and ideas and changes. -Damon

This isn’t meant to be a full-fledged tracking application (see django-tracking) or a real analytic tool (try Google Analytics); rather, it’s meant to simply count the number of hits/view on an object-per-object basis.

How to install:

I find that the easiest way to work with django apps is to symbolically link them to my site-packages directory. It’s easier to update the apps with svn, git, or hg than it is to manually download the files and install by hand.

For me, this is what it looks like (you can cut and paste to make it easy):

  • cd ~/src
  • git clone git://
  • sudo ln -s `pwd`/django-hitcount/hitcount `python -c "from distutils.sysconfig import get_python_lib; print get_python_lib()"`/hitcount

Test it works by loading python and checking the version (should not get an error):

>>> import hitcount
>>> hitcount.__version__
'0.1 alpha'

Adding to your django project:

Add the hitcount app to your INSTALLED_APPS tuple and run syncdb.

There are three additional settings you can add to your file:


HITCOUNT_KEEP_HIT_ACTIVE: is the number of days, weeks, months, hours, etc (timedelta kwargs), that an Hit is kept ‘active’. If a Hit is ‘active’ a repeat viewing will not be counted. After the active period ends, however, a new Hit will be recorded. You can decide how long you want this period to last …

HITCOUNT_HITS_PER_IP_LIMIT: limit the number of ‘active’ hits from a single IP address. 0 means that it is unlimited. You may want to set this, or not.

HITCOUNT_EXCLUDE_USER_GROUP: don’t count any hits from certain logged in users. In the example above, I don’t want any of my editors inflating the total Hit count.

Adding to your

You need to add one line to your file.

You can have this url, itself, point to anywhere you like, but you need to keep the name='hitcount_update_ajax' constant.

from django.conf.urls.defaults import *
from django.views.generic.list_detail import object_detail
from hitcount.views import update_hit_count_ajax

urlpatterns = patterns('',
    url(r'^ajax/hit/$', # you can change this url if you would like
        name='hitcount_update_ajax'), # keep this name the same

    # other views, for example my object view is:

    url(r'^/video/(?P<object_id>\d+)$', object_detail,
        {   'queryset': Video.objects.all(),
            'template_name': "video/view.html"},


Edit your templates

Add the javascript to your object_detail templates (or any template that handles a single object) so that our hit counter is called after the document loads.

Here is what my head includes:

{% load hitcount_tags %}
<script src="/media/js/jquery-latest.js" type="text/javascript"></script>
<script type="text/javascript"><!--
    $(document).ready(function() {
        {% get_hit_count_javascript for object %}

When the template is rendered, it should turn into something like this:

$(document).ready(function() {

$.post( '/ajax/hit/',
	{ hitcount_pk : '3' },
	function(data, status) {
		if (data.status == 'error') {
			// do something for error?


Display the hits!

The most exciting part, is actually displaying your hits. There are four different ways to do it:

    - Return total hits for an object: 
      {% get_hit_count for [object] %}
    - Get total hits for an object as a specified variable:
      {% get_hit_count for [object] as [var] %}
    - Get total hits for an object over a certain time period:
      {% get_hit_count for [object] within ["days=1,minutes=30"] %}

    - Get total hits for an object over a certain time period as a variable:
      {% get_hit_count for [object] within ["days=1,minutes=30"] as [var] %}

40 Comments (newest first)

  1. Ajay says:

    i have been trying to implement this app and viewing comments in this thread shows its very easy one too.
    i have followed your tutorial with each step clearly done.
    I have a Model named Package for which i want to implement this app.
    everything works fine but the hitcount are not increasing on multiple access of same package eventhough the limit is set to 0. i have even tried it 10 or other numbers as well.
    pls help!

  2. Fred says:

    Getting RuntimeWarning: DateTimeField received a naive datetime.

    I would like to request an enhancement to make the app datetime aware.

  3. […] trying to use the django-hitcount module to save the number of times a tutorial is accessed by different […]

  4. Sergey says:

    Thanx a lot, nice app!
    You should check Pull request from zaebee on github, it solve csrf problem on latest django release.

  5. Fibo says:

    I followed your instructions but im getting this error:
    ‘str’ object has no attribute ‘_meta’
    dont know where i went wrong.

  6. Hi!

    One little detail, depicted with an screenshot:


    Nice post!

  7. Praca za granic?…

    […]django-hitcount: simple app to count hits/views for an object «[…]…

    • Fred says:

      Can’t seem to get this to work on Mezzanine. Can someone please explain what I should substitute in for the “object”? How do I find that variable or whatever it is. An object means several different things in Django so it’s confusing.

      A real world example using the actual word rather then placeholder “object” word might help.

      • Fred says:

        Figured it out.

        You have to put custom urls above the:
        (“^”, include(“mezzanine.urls”)),
        pattern that is included in the mezzanine

  8. Barceló says:

    Sorry mi english is bad! :)

    I’ve problem when I add into:

    {% load hitcount_tags %}

    Look error:

  9. Barceló says:

    With django-hicount I can see the number of visits to the site?
    example: <—— hitcount show visits to this site

  10. Nick says:

    Easiest app I’ve installed. :). Thanks for the hard work!

  11. Dmitry says:

    To render 1 page hitcount makes 2 identical SQL queries:

    First to render js:

    and second to get hitcount for object:
    {% get_hit_count for object as hit_count %}

    How can I reduce the number of queries?)

  12. Jacquesknie says:

    How would I order my counted objects by hits in a view? I really can’t get my head around these generic relations!

    • Dmitry says:

      Use something like this:
      actions = Action.objects.all().extra(
      ‘hit_count': ‘SELECT hits FROM hitcount_hit_count as t \
      WHERE t.content_type_id = 13 \
      AND t.object_pk =’,

      It works =)

      • Jacquesknie says:

        Hey Dmitry,
        Thanks for your reply, but I still don’t really get it. I have a model called Card, how would your code look like then?
        For Example:
        sorted_cards = Card.objects.all().extra(…).order_by(…)

        I’m quite new to all this and don’t have a clue about sql and things like that. Your help is really appreciated.


        • Umberto says:

          This app should integrate django as it is really handy.

          I’m using django 1.3.

          I think the problem of getting a top-hits list of objects is already solved because the hitcount.models.HitCount has a content_object field, which returns the target object.

          All I did was:

          qs = models.HitCount.objects.order_by(‘-hits’)

          qs[i].content_object refers to the object instance.

          You can always use Model.objects.values_list() to get an actual list of your objects:

          qs = models.HitCount.objects.values_list(‘content_object’, flat=True).order_by(‘-hits’)

  13. Sam Starling says:

    I know nothing has been posted here for a while, but I’ve just started using this. It’s very useful, but the AJAX calls will fail when the CsrfViewMIddleware is installed in MIDDLEWARE_CLASSES (which it is by default in Django).

    To solve this, you need to make sure you include the appropriate CSRF Header in every AJAX request, which can be done as shown in the Django documentation.

    • Damon says:

      Which version of Django does this fail with? I haven’t updated my web site that utilizes this lately so I may be behind in the Django parlance — in fact, haven’t done anything with this for a bit! Feel bad too – need to get on that.

      • Sam Starling says:

        I’m using 1.2.5 – however, it’s easily fixed by using the Javascript given on that Django page I linked originally. I hadn’t realised that the function posted there overrides every AJAX POST and adds in the appropriate header, thus solving the problem!

  14. Friend says:

    Nice app, works fine!

    Can you tell, how to make query (in views i suggest) to display 50 items on page, each item must have number of views

    If i use template tag “get_hit_count for [object] as [var]” i get too many sql queries

    Can i use something like select_related() to get all statistics in one query?


  15. Why do you include the ajax call? Wouldn’t it be much simpler to just update your db via the template tag? It seems that including a POST request is unnecessary.

    • Damon says:

      You could do that – however, the AJAX approach is just one way to try and counter ‘false counts’ … if it was triggered by a database hit (or page load) all the web crawlers and bots would set off hits every time the page read … which would be a lot. AJAX, hopefully, helps to ensure that only real computer users are triggering a hit.

      • Hmmm I guess that makes sense…although for bots one step could be to check the user-agent string. It wouldn’t prevent people purposefully spamming, but then neither would the ajax method.

        • As far as bot checking goes, it looks like you could either run the UA past all of the known bot UA strings ( or just check for the major browsers.

          • Damon says:

            That’s a great idea!

            I would love to implement some alternative methods to recording a Hit … if you look under the you’ll see I separated the base Hit processing method [_update_hit_count(request, hitcount)] from the ajax method.

            If you wanted to fork the project and add another view method that utilizes the UA list and doesn’t require javascript, I would be happy to test it and merge it into the master branch. I think it would be useful for people who aren’t already using jQuery.

            If you aren’t up for it, I will try and add that feature when I have a chance … contact via github if you are interested.

            Thanks for the idea!

          • Damon says:

            I opened a ticket:


            Comment there with input. Shouldn’t be that hard to implement … importing the list of UA’s will be the major work … if it can be called that.

    • leon says:

      I’m interested in using this to count impressions of adds not just requests for them. I want my advertisers to know when there add has been “seen” not just requested. I’m planing on attaching the hit count to 2 js events – when the add in in visible range and when an add has been display in a fading group of adds. this will be perfect! thanks :)

  16. Matt says:

    I haven’t tried this out yet, I’m planning on implementing it tonight. It’s exactly what I was looking for. I hope it works out wells. Cheers.

    • Damon says:

      Let me know how it works – it isn’t as full-featured as I would like, yet, but seems to get the job done so far. If you have any contributions to make would love to incorporate them.

      • Matt says:

        Hi Damon. So far so good. I’m actually fairly new to Django and had a question. I’m making a video site and am using this to keep track of video views. Lets say I wanted to display the last 2 videos that recorded a view, could I do that using your app? I’m having trouble figuring it out (this is the first website I’m actually programming, so I don’t know too much..). If you have some sort of answer to that, feel free to email me as well. Thank you!

        • Damon says:

          Well, every time a Hit is saved the associated HitCount objects modified value is updated. So, you could get the last two like so:

          >>> from hitcount.models import HitCount
          >>> for hc in HitCount.objects.order_by('-modified')[:2]:
          ...   hc.content_object
          <Video: Stars & Stripes FOREVER! [HD]>
          <Video: The Muppets Bohemian Rhapsody>

          That should get you started …

  17. Amazing, man. Works out of the box!
    Thanks a lot!!

  18. Nice, thanks for this. You forgot to add the following command templates:
    {% load hitcount_tags %}