Skip to main content

A Django app for l10n of postal addresses.

Project description


(Based upon

A django application that provides a location agnostic model for postal addresses.

The motivation behind this project is that most countries have different forms of postal addresses e.g. ,

This app assumes that all postal addresses worldwide can be made up of 5 optional address lines plus a country code.

It then localizes the title of each line dependant on the country selected. Further information on each address line can be gleaned from django.contrib.localflavor fields and widgets e.g. for the UK

from django import forms
from django.utils.translation import ugettext_lazy as _
from import UKPostcodeField, UKCountySelect

from postal.forms import PostalAddressForm

class GBPostalAddressForm(PostalAddressForm):
    line1 = forms.CharField(label=_(u"Street"), required=False, max_length=50)
    line2 = forms.CharField(label=_(u"Area"), max_length=50)
    city = forms.CharField(label=_(u"Town"), max_length=50)
    state = forms.CharField(label=_(u"County"), widget=UKCountySelect, max_length=50)
    code = UKPostcodeField(label=_(u"Postcode"))

It is hoped that various contributors will contribute address formats per country and that eventually this address information could find it’s way back in to django.contrib.localflavor


django-countries (


1. Add django-countries and django-postal to your INSTALLED_APPS in e.g.:

  1. Add a postal_form to your templates:

    {% load postal_tags %}
            <script src="{{ MEDIA_URL }}js/jquery-1.4.2.min.js" type="text/javascript" charset="utf-8"></script>
        <form method="POST" action="">
            {% csrf_token %}
            {% monitor_country_change %}
            <script type="text/javascript">
            <input type="submit"/>

Changing the country in the form above should localise the address form.

  1. In your view code add code to save the addressform e.g.:

    from postal.forms import PostalAddressForm
    def my_view(request)
        if request.method == "POST":
            address_form = PostalAddressForm(request.POST, prefix=request.POST.get('prefix', ''))

How to use localised addresses

Address localisation is turned on by default. To turn off Address l10n in set:


Customize address labels and requirement

If you wish to customize the address labels and whether the address line is required or not, you can add the following variables to


Each of these variables is set to a tuple of the format ('label', True/False) label is used to label the field, and the second boolean value sets whether the field is required or not, e.g.:

POSTAL_ADDRESS_LINE1 = ("Department", True)


0.9.6 Remove django-piston requirement Fixed django 1.7 compatibility issues Added Italian Postal Address Form (Thanks to Francesco Facconi for above changes)

0.7.2 Major refactor where all models removed so django-postal just provides localized forms. It is up to the supporting project to define their own address models

0.4 Don’t enforce uniqueness on postal addresses

Developers, How to Contribute

Git foo:

$ git clone
$ cd django-postal
$ virtualenv . --no-site-packages
$ source bin/activate
$ python
$ bin/buildout -v
$ bin/django syncdb
$ bin/django test postal
$ bin/django runserver

Browse to http://localhost:8000

New countries can be added to the src/postal/forms folder by their 2 letter country code e.g. us

Each country folder contains an and a contains the localized address.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

django-postal-0.96.tar.gz (44.5 kB view hashes)

Uploaded Source

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page