Installation & configuration


The easiest way to install Photologue is with pip; this will give you the latest version available on PyPi:

pip install django-photologue

You can also take risks 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. However, we strongly recommend that you stick with a release from the PyPi repository, unless if you’re confident in your abilities to fix any potential bugs on your own!

Python 3

Photologue is compatible with Python 3 (3.3 or later).


3 apps that will be installed automatically if required.

And 1 dependency that you will have to manage yourself:


Photologue tries to support the same Django version as are supported by the Django project itself.

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!

  1. Pillow is a fork of PIL; you should not have installed both - this can cause strange bugs.

  2. 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 display 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 file

Follow these 4 steps:

  1. Add to your INSTALLED_APPS setting:

         # ...other installed applications...
  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.

  4. Enable the Django sites framework if you have not already done so. This is not enabled by default in Django, but is required by Photologue.

Add the urls

Add photologue to your projects file:

urlpatterns += [
    url(r'^photologue/', include('photologue.urls', namespace='photologue')),

Sync Your Database

You can now sync your database:

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!

Instant templates

Photologue comes with basic templates for galleries and photos, which are designed to work well with Twitter-Bootstrap. You can of course use them, or override them, or completely replace them. Note that all Photologue templates inherit from photologue/root.html, which itself expects your site’s base template to be called base.html - you can change this to use a different base template.


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 cases you may want to have gallery pages, but no photo detail page (e.g. if all photos are displayed via a javascript lightbox).


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.

Amazon S3

Photologue can use a custom file storage system, for example Amazon’s S3.

You will need to configure your Django project to use Amazon S3 for storing files; a full discussion of how to do this is outside the scope of this page.

However, there is a quick demo of using Photologue with S3 in the example_project directory; if you look at these files:

  • example_project/example_project/
  • example_project/requirements.txt

At the end of each file you will commented-out lines for configuring S3 functionality. These point to extra files stored under example_project/example_storages/. Uncomment these lines, run the example project, then study these files for inspiration! After that, setting up S3 will consist of (at minimum) the following steps:

  1. Signup for Amazon AWS S3 at
  2. Create a Bucket on S3 to store your media and static files.
  3. Set the environment variables:
    • AWS_ACCESS_KEY_ID - issued to your account by S3.
    • AWS_SECRET_ACCESS_KEY - issued to your account by S3.
    • AWS_STORAGE_BUCKET_NAME - name of your bucket on S3.
  4. To copy your static files into your S3 Bucket, type python collectstatic in the example_project directory.


This simple setup does not handle S3 regions.