django-countries 7.4

Installation

1. pip install django-countries

   For more accurate sorting of translated country names, install it with the optional pyuca package:

   pip install django-countries[pyuca]

2. Add django_countries to INSTALLED_APPS

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)')

You can filter using the full English country names, even though only the country codes are stored in the database (using contains, startswith, endswith, regex, and their case insensitive versions). Use __name or __iname for the “exact”/”iexact” equivalent:

>>> Person.objects.filter(country__name="New Zealand").count()
1
>>> Person.objects.filter(country__icontains="zealand").count()
1

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 model field’s custom form field to ensure the translatable strings for the country choices are left lazy until the widget renders:

from django_countries.fields import CountryField

class CustomForm(forms.Form):
    country = CountryField().formfield()

Use CountryField(blank=True) for non-required form fields, and CountryField(blank_label='(Select country)') to use a custom label for the initial blank option.

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(f"{name} ({code})")
...
Afghanistan (AF)
Åland Islands (AX)
Albania (AL)

Country names are translated using Django’s standard gettext. 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 }}

If you need a list of countries, there’s also a simple tag for that:

{% load countries %}
{% get_countries as countries %}
<select>
{% for country in countries %}
    <option value="{{ country.code }}">{{ country.name }}</option>
{% endfor %}
</select>

Customization

from django.utils.translation import gettext_lazy as _

COUNTRIES_OVERRIDE = {
    'NZ': _('Middle Earth'),
    'AU': None,
    'US': {'names': [
        _('United States of America'),
        _('America'),
    ],
}

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()

setup(
    ...
    entry_points={
        'django_countries.Country': 'phone = django_countries_phone.get_phone'
    },
    ...
)

Django Rest Framework

Django Countries ships with a CountryFieldMixin to make the CountryField model field compatible with DRF serializers. Use the following mixin with your model serializer:

from django_countries.serializers import CountryFieldMixin

class CountrySerializer(CountryFieldMixin, serializers.ModelSerializer):

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

This mixin handles both standard and multi-choice country fields.

from django_countries.serializer_fields import CountryField

class CountrySerializer(serializers.Serializer):
    country = CountryField()

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

OPTIONS /api/address/ HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/json
Allow: GET, POST, HEAD, OPTIONS

{
"actions": {
  "POST": {
    "country": {
    "type": "choice",
    "label": "Country",
    "choices": [
      {
        "display_name": "Australia",
        "value": "AU"
      },
      [...]
      {
        "display_name": "United Kingdom",
        "value": "GB"
      }
    ]
  }
}

GraphQL

A Country graphene object type is included that can be used when generating your schema.

import graphene
from graphene_django.types import DjangoObjectType
from django_countries.graphql.types import Country

class Person(ObjectType):
    country = graphene.Field(Country)

    class Meta:
        model = models.Person
        fields = ["name", "country"]

The object type has the following fields available:

• name for the full country name

• code for the ISO 3166-1 two character country code

• alpha3 for the ISO 3166-1 three character country code

• numeric for the ISO 3166-1 numeric country code

• iocCode for the International Olympic Committee country code

7.4 (7 October 2022)

• Fixed Traditional Chinese translation (needed to be locale/zh_Hant).

• Update flag of Honduras.

• Add Django 4.0 and 4.1 to the test matrix, dropping 3.0 and 3.1

• Add Django Rest Framework 3.13 and 3.14, dropping 3.11.

• Multi-choice countries are now stored sorted and with duplicates stripped. Thanks flbraun and Jens Diemer!

• Fix common country names not being honoured in non-English translations.

7.3.2 (4 March 2022)

• Fix slowdown introduced in v7.3 caused by always using country name lookups for field comparisons. filter(country="New Zealand") will no longer match now, but instead new __name and __iname filters have been added to achieve this.

7.3.1 (1 March 2022)

• Typing compatibility fixes for Python <3.9.

7.3 (28 February 2022)

• Make full English country names work in database lookups, for example, Person.objects.filter(country__icontains="zealand").

7.2.1 (11 May 2021)

• Fix Latin translations.

7.2 (10 May 2021)

• Allow the character field to work with custom country codes that are not 2 characters (such as “GB-WLS”).

• Fix compatibility with django-migrations-ignore-attrs library.

7.1 (17 March 2021)

• Allow customising the str_attr of Country objects returned from a CountryField via a new countries_str_attr keyword argument (thanks C. Quentin).

• Add pyuca as an extra dependency, so that it can be installed like pip install django-countries[pyuca].

• Add Django 3.2 support.

7.0 (5 December 2020)

• Add name_only as an option to the Django Rest Framework serializer field (thanks Miguel Marques).

• Add in Python typing.

• Add Python 3.9, Django 3.1, and Django Rest Framework 3.12 support.

• Drop Python 3.5 support.

• Improve IOC code functionality, allowing them to be overridden in COUNTRIES_OVERRIDE using the complex dictionary format.

6.1.3 (18 August 2020)

• Update flag of Mauritania.

• Add flag for Kosovo (under its temporary code of XK).

6.1.2 (26 March 2020)

• Fix Python 3.5 syntax error (no f-strings just yet…).

6.1.1 (26 March 2020)

• Change ISO country import so that “Falkland Islands [Malvinas]” => “Falkland Islands (Malvinas)”.

6.1 (20 March 2020)

• Add a GraphQL object type for a django Country object.

6.0 (28 February 2020)

• Make DRF CountryField respect blank=False. This is a backwards incompatible change since blank input will now return a validation error (unless blank is explicitly set to True).

• Fix COUNTRIES_OVERRIDE when using the complex dictionary format and a single name.

• Add bandit to the test suite for basic security analysis.

• Drop Python 2.7 and Python 3.4 support.

• Add Rest Framework 3.10 and 3.11 to the test matrix, remove 3.8.

• Fix a memory leak when using PyUCA. Thanks Meiyer (aka interDist)!

5.5 (11 September 2019)

• Django 3.0 compatibility.

• Plugin system for extending the Country object.

5.4 (11 August 2019)

• Renamed Macedonia -> North Macedonia.

• Fix an outlying makemigrations error.

• Pulled in new translations which were provided but missing from previous version.

• Fixed Simplified Chinese translation (needed to be locale/zh_Hans).

• Introduce an optional complex format for COUNTRIES_ONLY and COUNTRIES_OVERRIDE to allow for multiple names for a country, a custom three character code, and a custom numeric country code.

5.3.3 (16 February 2019)

• Add test coverage for Django Rest Framework 3.9.

5.3.2 (27 August 2018)

• Tests for Django 2.1 and Django Rest Framework 3.8.

5.3.1 (12 June 2018)

• Fix dumpdata and loaddata for CountryField(multiple=True).

5.3 (20 April 2018)

• Iterating a Countries object now returns named tuples. This makes things nicer when using {% get_countries %} or using the country list elsewhere in your code.

5.2 (9 March 2018)

• Ensure Django 2.1 compatibility for CountrySelectWidget.

• Fix regression introduced into 5.1 when using Django 1.8 and certain queryset lookup types (like __in).

5.1.1 (31 January 2018)

• Fix some translations that were included in 5.1 but not compiled.

5.1 (30 January 2018)

• Tests now also cover Django Rest Framework 3.7 and Django 2.0.

• Allow for creating country fields using (valid) alpha-3 or numeric codes.

• Fix migration error with blank default (thanks Jens Diemer).

• Add a {% get_countries %} template tag (thanks Matija Čvrk).

5.0 (10 October 2017)

• No longer allow multiple=True and null=True together. This causes problems saving the field, and null shouldn’t really be used anyway because the country field is a subclass of CharField.

4.6 (16 June 2017)

• Add a CountryFieldMixin Django Rest Framework serializer mixin that automatically picks the right field type for a CountryField (both single and multi-choice).

• Validation for Django Rest Framework field (thanks Simon Meers).

• Allow case-insensitive .by_name() matching (thanks again, Simon).

• Ensure a multiple-choice CountryField.max_length is enough to hold all countries.

• Fix inefficient pickling of countries (thanks Craig de Stigter for the report and tests).

• Stop adding a blank choice when dealing with a multi-choice CountryField.

• Tests now cover multiple Django Rest Framework versions (back to 3.3).

4.5 (18 April 2017)

• Change rest framework field to be based on ChoiceField.

• Allow for the rest framework field to deserialize by full country name (specifically the English name for now).

4.4 (6 April 2017)

• Fix for broken CountryField on certain models in Django 1.11. Thanks aktiur for the test case.

• Update tests to cover Django 1.11

4.3 (29 March 2017)

• Handle “Czechia” translations in a nicer way (fall back to “Czech Republic” until new translations are available).

• Fix for an import error in Django 1.9+ due to use of non-lazy ugettext in the django-countries custom admin filter.

• Back to 100% test coverage.

4.2 (10 March 2017)

• Add sprite flag files (and Country.flag_css property) to help minimize HTTP requests.

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!

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!

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.

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.

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.

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.

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)

2.1 (24 Mar 2014)

• Add IOC (3 letter) country codes.

• Fix bug when loading fixtures.

2.0 (18 Feb 2014)

This is the first entry to the change log. The previous 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.