.. image:: https://badge.fury.io/py/django-countries.svg :alt: PyPI version :target: https://badge.fury.io/py/django-countries
.. image:: https://github.com/SmileyChris/django-countries/actions/workflows/tests.yml/badge.svg :alt: Build status :target: https://github.com/SmileyChris/django-countries/actions/workflows/tests.yml
A Django application that provides country choices for use with forms, flag icons static files, and a country field for models.
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/smileychris/django-countries/
.. contents:: :local: :backlinks: none
pip install django-countries
For more accurate sorting of translated country names, install it with the optional pyuca_ package:
pip install django-countries[pyuca]
Add django_countries to INSTALLED_APPS
.. _pyuca: https://pypi.python.org/pypi/pyuca/
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:
.. code:: python
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:
.. code:: python
>>> 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:
.. code:: python
country = CountryField(blank_label="(select country)")
You can filter using the full English country names in addition to country
codes, even though only the country codes are stored in the database by using
the queryset lookups contains, startswith, endswith, regex, or
their case insensitive versions. Use __name or __iname for the
exact/iexact equivalent:
.. code:: python
>>> Person.objects.filter(country__name="New Zealand").count()
1
>>> Person.objects.filter(country__icontains="zealand").count()
1
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:
.. code:: python
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
By default, countries are stored sorted for data consistency, and any
duplicates are removed. These behaviours can be overridden by using the field
arguments multiple_sort=False and multiple_unique=False respectively.
Country objectAn object used to represent a country, instantiated with a two character country code, three character code, or numeric code.
It can be compared to other objects as if it was a string containing the country code and when evaluated as text, returns the country code.
name Contains the full country name.
flag
Contains a URL to the flag. If you page could have lots of different flags
then consider using flag_css instead to avoid excessive HTTP requests.
flag_css Output the css classes needed to display an HTML element as the correct flag from within a single sprite image that contains all flags. For example:
.. code:: jinja
<link rel="stylesheet" href="{% static 'flags/sprite.css' %}">
<i class="{{ country.flag_css }}"></i>
For multiple flag resolutions, use sprite-hq.css instead and add the
flag2x, flag3x, or flag4x class. For example:
.. code:: jinja
<link rel="stylesheet" href="{% static 'flags/sprite-hq.css' %}">
Normal: <i class="{{ country.flag_css }}"></i>
Bigger: <i class="flag2x {{ country.flag_css }}"></i>
You might also want to consider using aria-label for better
accessibility:
.. code:: jinja
<i class="{{ country.flag_css }}"
aria-label="{% blocktrans with country_code=country.code %}
{{ country_code }} flag
{% endblocktrans %}"></i>
unicode_flag A unicode glyph for the flag for this country. Currently well-supported in iOS and OS X. See https://en.wikipedia.org/wiki/Regional_Indicator_Symbol for details.
code The two letter country code for this country.
alpha3 The three letter country code for this country.
numeric The numeric country code for this country (as an integer).
numeric_padded The numeric country code as a three character 0-padded string.
ioc_code The three letter International Olympic Committee country code.
CountrySelectWidgetA widget is included that can show the flag image after the select box (updated with JavaScript when the selection changes).
When you create your form, you can use this custom widget like normal:
.. code:: python
from django_countries.widgets import CountrySelectWidget
class PersonForm(forms.ModelForm):
class Meta:
model = models.Person
fields = ("name", "country")
widgets = {"country": CountrySelectWidget()}
Pass a layout text argument to the widget to change the positioning of the
flag and widget. The default layout is:
.. code:: python
'{widget}<img class="country-select-flag" id="{flag_id}" style="margin: 6px 4px 0" src="{country.flag}">'
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:
.. code:: python
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.
Use the django_countries.countries object instance as an iterator of ISO
3166-1 country codes and names (sorted by name).
For example:
.. code:: python
>>> 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)
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:
.. code:: jinja
{% load countries %}
{% get_country 'BR' as country %}
{{ country.name }}
If you need a list of countries, there's also a simple tag for that:
.. code:: jinja
{% load countries %}
{% get_countries as countries %}
<select>
{% for country in countries %}
<option value="{{ country.code }}">{{ country.name }}</option>
{% endfor %}
</select>
Country names are taken from the official ISO 3166-1 list, with some country names being replaced with their more common usage (such as "Bolivia" instead of "Bolivia, Plurinational State of").
To retain the official ISO 3166-1 naming for all fields, set the
COUNTRIES_COMMON_NAMES setting to False.
If your project requires the use of alternative names, the inclusion or
exclusion of specific countries then set the COUNTRIES_OVERRIDE setting to
a dictionary of names which override the defaults. The values can also use a
more complex dictionary format_.
Note that you will need to handle translation of customised country names.
Setting a country's name to None will exclude it from the country list.
For example:
.. code:: python
from django.utils.translation import gettext_lazy as _
COUNTRIES_OVERRIDE = {
"NZ": _("Middle Earth"),
"AU": None,
"US": {
"names": [
_("United States of America"),
_("America"),
],
},
}
If you have a specific list of countries that should be used, use
COUNTRIES_ONLY:
.. code:: python
COUNTRIES_ONLY = ["NZ", "AU"]
or to specify your own country names, use a dictionary or two-tuple list (string items will use the standard country name):
.. code:: python
COUNTRIES_ONLY = [
"US",
"GB",
("NZ", _("Middle Earth")),
("AU", _("Desert")),
]
Provide a list of country codes as the COUNTRIES_FIRST setting and they
will be shown first in the countries list (in the order specified) before all
the alphanumerically sorted countries.
If you want to sort these initial countries too, set the
COUNTRIES_FIRST_SORT setting to True.
By default, these initial countries are not repeated again in the
alphanumerically sorted list. If you would like them to be repeated, set the
COUNTRIES_FIRST_REPEAT setting to True.
Finally, you can optionally separate these "first" countries with an empty
choice by providing the choice label as the COUNTRIES_FIRST_BREAK setting.
The COUNTRIES_FLAG_URL setting can be used to set the url for the flag
image assets. It defaults to:
.. code:: python
COUNTRIES_FLAG_URL = "flags/{code}.gif"
The URL can be relative to the STATIC_URL setting, or an absolute URL.
The location is parsed using Python's string formatting and is passed the following arguments:
codecode_upperFor example: COUNTRIES_FLAG_URL = "flags/16x10/{code_upper}.png"
No checking is done to ensure that a static flag actually exists.
Alternatively, you can specify a different URL on a specific CountryField:
.. code:: python
class Person(models.Model):
name = models.CharField(max_length=100)
country = CountryField(
countries_flag_url="//flags.example.com/{code}.png")
To customize an individual field, rather than rely on project level settings,
create a Countries subclass which overrides settings.
To override a setting, give the class an attribute matching the lowercased
setting without the COUNTRIES_ prefix.
Then just reference this class in a field. For example, this CountryField
uses a custom country list that only includes the G8 countries:
.. code:: python
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()
For COUNTRIES_ONLY and COUNTRIES_OVERRIDE, you can also provide a
dictionary rather than just a translatable string for the country name.
The options within the dictionary are:
name or names (required)
Either a single translatable name for this country or a list of multiple
translatable names. If using multiple names, the first name takes preference
when using COUNTRIES_FIRST or the Country.name.
alpha3 (optional)
An ISO 3166-1 three character code (or an empty string to nullify an existing
code for this country.
numeric (optional)
An ISO 3166-1 numeric country code (or None to nullify an existing code
for this country. The numeric codes 900 to 999 are left available by the
standard for user-assignment.
ioc_code (optional)
The country's International Olympic Committee code (or an empty string to
nullify an existing code).
Country object external pluginsOther Python packages can add attributes to the Country_ object by using entry points in their setup script.
.. Country: The Country object
For example, you could create a django_countries_phone package which had a
with the following entry point in the setup.py file. The entry point name
(phone) will be the new attribute name on the Country object. The attribute
value will be the return value of the get_phone function (called with the
Country instance as the sole argument).
.. code:: python
setup( ... entry_points={ "django_countries.Country": "phone = django_countries_phone.get_phone" }, ... )
Django Countries ships with a CountryFieldMixin to make the
CountryField_ model field compatible with DRF serializers. Use the following
mixin with your model serializer:
.. code:: python
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.
For lower level use (or when not dealing with model fields), you can use the
included CountryField serializer field. For example:
.. code:: python
from django_countries.serializer_fields import CountryField
class CountrySerializer(serializers.Serializer):
country = CountryField()
You can optionally instantiate the field with the countries argument to
specify a custom Countries_ instance.
.. Countries: Single field customization
REST output format ^^^^^^^^^^^^^^^^^^
By default, the field will output just the country code. To output the full
country name instead, instantiate the field with name_only=True.
If you would rather have more verbose output, instantiate the field with
country_dict=True, which will result in the field having the following
output structure:
.. code:: json
{"code": "NZ", "name": "New Zealand"}
Either the code or this dict output structure are acceptable as input
irregardless of the country_dict argument's value.
When you request OPTIONS against a resource (using the DRF metadata support_)
the countries will be returned in the response as choices:
.. code:: text
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"
}
]
}
}
.. _metadata support: http://www.django-rest-framework.org/api-guide/metadata/
A Country graphene object type is included that can be used when generating
your schema.
.. code:: python
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 namecode for the ISO 3166-1 two character country codealpha3 for the ISO 3166-1 three character country codenumeric for the ISO 3166-1 numeric country codeiocCode for the International Olympic Committee country codeThis log shows interesting changes that happen for each version, latest versions first. It can be assumed that translations have been updated each release, and any new translations added.
Replace deprecated pkg_resources.iter_entry_points with
importlib_metadata.
Support Django 5.0.
Make CountryField queryset filters also work with country codes in
addition to names.
Switch to pyproject.toml rather than setup.py to fix installation
issues with pip 23.0+.
Rename Turkey to Türkiye.
A change in v7.4 introduced multi-choice countries being stored sorted and
deduplicated. This remains the default behaviour going forwards, but these
can now be overridden via arguments on the CountryField.
Improve translation fallback handling, fixing a threading race condition that could cause odd translation issues. Thanks to Jan Wróblewski and Antoine Fontaine for their help in resolving this. This also fixes translation issues with older Python 3.6/3.7 versions.
Add Python 3.11, drop Python 3.6 and Django 2.2 support.
USE_I18N = False.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 (only fixed for Python 3.8+).
filter(country="New Zealand") will no longer match
now, but instead new __name and __iname filters have been added to
achieve this.Person.objects.filter(country__icontains="zealand").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.
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.
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.
Update flag of Mauritania.
Add flag for Kosovo (under its temporary code of XK).
Country object.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)!
Django 3.0 compatibility.
Plugin system for extending the Country object.
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.
dumpdata and loaddata for CountryField(multiple=True).Countries object now returns named tuples. This makes things
nicer when using {% get_countries %} or using the country list elsewhere
in your code.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).
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).
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.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).
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).
Fix for broken CountryField on certain models in Django 1.11. Thanks aktiur for the test case.
Update tests to cover Django 1.11
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.
Country.flag_css property) to help minimize
HTTP requests.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!
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!
COUNTRIES_FIRST_SORT (feature still worked, tests didn't).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.
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.
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.
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.
CHANGES.rst wasn't in the manifest)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)
Revert descriptor to always return a Country object.
Fix the CountryField widget choices appearing empty due to a translation
change in v3.0.
CountrySelectWidget failing when used with a model form that is
passed a model instance.Add IOC (3 letter) country codes.
Fix bug when loading fixtures.
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.
FAQs
Provides a country field for Django models.
We found that django-countries demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.
Research
Security News
Attackers used a malicious npm package typosquatting a popular ESLint plugin to steal sensitive data, execute commands, and exploit developer systems.
Security News
The Ultralytics' PyPI Package was compromised four times in one weekend through GitHub Actions cache poisoning and failure to rotate previously compromised API tokens.