Installation & configuration


The easiest way to install Photologue is with pip:

pip install django-photologue

You can also live life on the edge and install the latest code directly from the Github repository:

pip install -e git+

This code should work ok - like Django itself, we try to keep the master branch bug-free.

Python 3

Django from version 1.5 onwards works with Python 3.

Photologue also works with Python 3 (3.3 or later). Like Django itself, support for Python 3 can be described as “should work, but needs more time on production sites to prove itself”. Use it, but apply caution!


5 apps that will be installed automatically if required.

And 2 dependencies that you will have to manage yourself:


  • Photologue has the same support policy as Django.

That troublesome Pillow...

Pillow can be tricky to install; sometimes it will install smoothly out of the box, sometimes you can spend hours figuring it out - installation issues vary from platform to platform, and from one OS release to the next, so listing them all here would not be realistic. Google is your friend, and it’s worth noting that Pillow is a fork of PIL, so googling ‘PIL installation <your platform>’ can also help.

  1. You should not have installed both PIL and Pillow; this can cause strange bugs. Please uninstall PIL before you install Pillow.

  2. In some situations, you might not be able to use Pillow at all (e.g. if another package has a dependency on PIL). Photologue has a clumsy answer for this: write a temporary file /tmp/PHOTOLOGUE_NO_PILLOW, then install Photologue. This will tell Photologue to install without Pillow. It should work, but it hasn’t been tested!

  3. Sometimes Pillow will install... but is not actually installed. This ‘undocumented feature’ has been reported by a user on Windows. If you can’t get Photologue to disaply any images, check that you can actually import Pillow:

    $ python shell
    Python 3.3.1 (default, Sep 25 2013, 19:29:01)
    [GCC 4.7.3] on linux
    Type "help", "copyright", "credits" or "license" for more information.
    >>> from PIL import Image

Configure Your Django Settings

  1. Add to your INSTALLED_APPS setting:

         # ...other installed applications,
         'south',               # if it's not already in your INSTALLED_APPS.
  2. Confirm that your MEDIA_ROOT and MEDIA_URL settings are correct (Photologue will store uploaded files in a folder called ‘photologue’ under your MEDIA_ROOT).

  3. Enable the admin app if you have not already done so.

Add the urls

Add photologue to your projects file:

urlpatterns += patterns('',
    (r'^photologue/', include('photologue.urls')),

Sync Your Database

Use South to setup the new tables:

python migrate photologue

If you are installing Photologue for the first time, this will set up some default PhotoSizes to get you started - you are free to change them of course!


The Sitemaps protocol allows a webmaster to inform search engines about URLs on a website that are available for crawling. Django comes with a high-level framework that makes generating sitemap XML files easy.

Install the sitemap application as per the instructions in the django documentation, then edit your project’s and add a reference to Photologue’s Sitemap classes in order to included all the publicly-viewable Photologue pages:

from photologue.sitemaps import GallerySitemap, PhotoSitemap

sitemaps = {...
            'photologue_galleries': GallerySitemap,
            'photologue_photos': PhotoSitemap,

There are 2 sitemap classes, as in some case you may want to have gallery pages, but no photo detail page (e.g. if all photos are displayed via a javascript lightbox).


There is also a PhotologueSitemap class which combines the above 2 classes, but it will be removed in Photologue 3.0.


Photologue supports Django’s site framework since version 2.8. That means that each Gallery and each Photo can be displayed on one or more sites.

Please bear in mind that photos don’t necessarily have to be assigned to the same sites as the gallery they’re belonging to: each gallery will only display the photos that are on its site. When a gallery does not belong the current site but a single photo is, that photo is only accessible directly as the gallery won’t be shown in the index.


If you’re upgrading from a version earlier than 2.8 you don’t need to worry about the assignment of already existing objects to a site because a datamigration will assign all your objects to the current site automatically.


This feature is switched off by default. See here to enable it and for more information.