django-countries 4.1

Installation

1. pip install django-countries

2. Add django_countries to INSTALLED_APPS

For more accurate sorting of translated country names, install the optional pyuca package.

CountryField

A country field for Django models that provides all ISO 3166-1 countries as choices.

CountryField is based on Django’s CharField, providing choices corresponding to the official ISO 3166-1 list of countries (with a default max_length of 2).

Consider the following model using a CountryField:

from django.db import models
from django_countries.fields import CountryField

class Person(models.Model):
    name = models.CharField(max_length=100)
    country = CountryField()

Any Person instance will have a country attribute that you can use to get details of the person’s country:

>>> person = Person(name='Chris', country='NZ')
>>> person.country
Country(code='NZ')
>>> person.country.name
'New Zealand'
>>> person.country.flag
'/static/flags/nz.gif'

This object (person.country in the example) is a Country instance, which is described below.

Use blank_label to set the label for the initial blank choice shown in forms:

country = CountryField(blank_label='(select country)')

This field can also allow multiple selections of countries (saved as a comma separated string). The field will always output a list of countries in this mode. For example:

class Incident(models.Model):
    title = models.CharField(max_length=100)
    countries = CountryField(multiple=True)

>>> for country in Incident.objects.get(title='Pavlova dispute').countries:
...     print(country.name)
Australia
New Zealand

from django_countries.widgets import CountrySelectWidget

class PersonForm(forms.ModelForm):
    class Meta:
        model = models.Person
        fields = ('name', 'country')
        widgets = {'country': CountrySelectWidget()}

'{widget}<img class="country-select-flag" id="{flag_id}" style="margin: 6px 4px 0" src="{country.flag}">'

Custom forms

If you want to use the countries in a custom form, use the following custom field to ensure the translatable strings for the country choices are left lazy until the widget renders:

from django_countries.fields import LazyTypedChoiceField

class CustomForm(forms.Form):
    country = LazyTypedChoiceField(choices=countries)

You can also use the CountrySelectWidget as the widget for this field if you want the flag image after the select box.

Get the countries from Python

Use the django_countries.countries object instance as an iterator of ISO 3166-1 country codes and names (sorted by name).

For example:

>>> from django_countries import countries
>>> dict(countries)['NZ']
'New Zealand'

>>> for code, name in list(countries)[:3]:
...     print("{name} ({code})".format(name=name, code=code))
...
Afghanistan (AF)
Åland Islands (AX)
Albania (AL)

Country names are translated using Django’s standard ugettext. If you would like to help by adding a translation, please visit https://www.transifex.com/projects/p/django-countries/

Template Tags

If you have your country code stored in a different place than a CountryField you can use the template tag to get a Country object and have access to all of its properties:

{% load countries %}
{% get_country 'BR' as country %}
{{ country.name }}

Customization

COUNTRIES_OVERRIDE = {
    'NZ': _('Middle Earth'),
    'AU': None
}

COUNTRIES_ONLY = ['NZ', 'AU']

COUNTRIES_ONLY = [
    'US',
    'GB',
    ('NZ', _('Middle Earth')),
    ('AU', _('Desert')),
]

COUNTRIES_FLAG_URL = 'flags/{code}.gif'

class Person(models.Model):
    name = models.CharField(max_length=100)
    country = CountryField(
        countries_flag_url='//flags.example.com/{code}.png')

from django_countries import Countries

class G8Countries(Countries):
    only = [
        'CA', 'FR', 'DE', 'IT', 'JP', 'RU', 'GB',
        ('EU', _('European Union'))
    ]

class Vote(models.Model):
    country = CountryField(countries=G8Countries)
    approve = models.BooleanField()

Django Rest Framework field

Django Countries ships with a CountryField serializer field to simplify the REST interface. For example:

from django_countries.serializer_fields import CountryField

class PersonSerializer(serializers.ModelSerializer):
    country = CountryField()

    class Meta:
        model = models.Person
        fields = ('name', 'email', 'country')

You can optionally instantiate the field with countries with a custom Countries instance.

{"code": "NZ", "name": "New Zealand"}

Version 4.1 (22 February 2017)

• Better default Django admin filter when filtering a country field in a ModelAdmin.

• Fix settings to support Django 1.11

• Fix when using a model instance with a deferred country field.

• Allow CountryField to handle multiple countries at once!

• Allow CountryField to still work if Deferred.

• Fix a field with customized country list. Thanks pilmie!

Version 4.0 (16 August 2016)

Django supported versions are now 1.8+

• Drop legacy code

• Fix tests, 100% coverage

• IOS / OSX unicode flags function

• Fix widget choices on Django 1.9+

• Add COUNTRIES_FIRST_SORT. Thanks Edraak!

Version 3.4 (22 October 2015)

• Extend test suite to cover Django 1.8

• Fix XSS escaping issue in CountrySelectWidget

• Common name changes: fix typo of Moldova, add United Kingdom

• Add {% get_country %} template tag.

• New CountryField Django Rest Framework serializer field.

Version 3.3 (30 Mar 2015)

• Add the attributes to Countries class that can override the default settings.

• CountriesField can now be passed a custom countries subclass to use, which combined with the previous change allows for different country choices for different fields.

• Allow COUNTRIES_ONLY to also accept just country codes in its list (rather than only two-tuples), looking up the translatable country name from the full country list.

• Fix Montenegro flag size (was 12px high rather than the standard 11px).

• Fix outdated ISO country name formatting for Bolivia, Gambia, Holy See, Iran, Micronesia, and Venezuela.

Version 3.2 (24 Feb 2015)

• Fixes initial iteration failing for a fresh Countries object.

• Fix widget’s flag URLs (and use ensure widget is HTML encoded safely).

• Add countries.by_name(country, language='en') method, allowing lookup of a country code by its full country name. Thanks Josh Schneier.

Version 3.1 (15 Jan 2015)

• Start change log :)

• Add a COUNTRIES_FIRST setting (and some other related ones) to allow for specific countries to be shown before the entire alphanumeric list.

• Add a blank_label argument to CountryField to allow customization of the label shown in the initial blank choice shown in the select widget.

Version 3.0 (22 Oct 2014)

Django supported versions are now 1.4 (LTS) and 1.6+

• Add COUNTRIES_ONLY setting to restrict to a specific list of countries.

• Optimize country name translations to avoid exessive translation calls that were causing a notable performance impact.

• PyUCA integration, allowing for more accurate sorting across all locales. Also, a better sorting method when PyUCA isn’t installed.

• Better tests (now at 100% test coverage).

• Add a COUNTRIES_FLAG_URL setting to allow custom flag urls.

• Support both IOC and numeric country codes, allowing more flexible lookup of countries and specific code types.

• Field descriptor now returns None if no country matches (reverted in v3.0.1)

Version 2.1 (24 Mar 2014)

• Add IOC (3 letter) country codes.

• Fix bug when loading fixtures.

Version 2.0 (18 Feb 2014)

This is the first entry to the change log. The previous version was 1.5, released 19 Nov 2012.

• Optimized flag images, adding flags missing from original source.

• Better storage of settings and country list.

• New country list format for fields.

• Better tests.

• Changed COUNTRIES_FLAG_STATIC setting to COUNTRIES_FLAG_URL.