django-countries

Django Countries provides several key capabilities for Django developers:

• Country Field: A dedicated Django model field containing all ISO 3166-1 countries.
• Translated Names: Country names are integrated with Django's i18n system for translation.
• Flag Icons: Includes static flag image files for all countries.
• REST Framework: Full integration with Django REST Framework.
• GraphQL: Support for graphene-django.
• Multiple Selection: Support for selecting multiple countries.

By default, django-countries provides user-friendly alternatives for verbose official ISO names via the COMMON_NAMES dictionary. This is useful for simplifying names like Bolivia (Plurinational State of) to just Bolivia or Korea (the Democratic People's Republic of) to North Korea.

When the COUNTRIES_COMMON_NAMES setting is enabled (which is the default), these friendly names are used in dropdown lists and displays instead of the official ISO names.

Dynamic country ordering is optimized for performance using a caching mechanism:

• First call cost: The initial iteration for a specific language/ordering combination incurs a cost for translation and sorting.
• Subsequent calls: Once computed, results are fully cached and very fast.
• Memory usage: Each unique combination of language and ordering configuration creates exactly one cache entry.
• Thread safety: The implementation uses asgiref.local.Local to ensure thread-local context safety.

This caching strategy makes dynamic ordering suitable for high-traffic applications.

You can add new attributes to the Country object from external Python packages using entry points. The entry point name becomes the attribute name on the Country instance, and its value is the return value of the registered function (which receives the Country instance as its only argument).

To implement this, register an entry point under the group django_countries.Country in your package's installation configuration.

The library follows the ISO 3166-1 standard for country names, which includes specific punctuation patterns for sorting and qualifiers:

• Parentheses ( ): Used for qualifiers, state designations, or articles (e.g., Bolivia (Plurinational State of) or Gambia (the)). These are not used for alphabetical inversion.
• Commas , : Used to indicate an inversion for alphabetical sorting, where the distinctive word appears first (e.g., Tanzania, the United Republic of).
• Multi-territory lists: Commas are also used as literal separators for lists of territories (e.g., Saint Helena, Ascension and Tristan da Cunha).

Note that django-countries automatically strips standalone (the) from names (e.g., Gambia (the) becomes Gambia), but preserves (the) when it is part of a longer phrase or when it is capitalized (e.g., Bahamas (The)).

The CountryField serializer field is flexible with input. Regardless of your configured output format, it accepts:

1. A country code string (e.g., "NZ").
2. A verbose dictionary (e.g., {"code": "NZ", "name": "New Zealand"}).
3. Country names, which will resolve to the correct code based on Django's active language (e.g., "Germany" or "Allemagne" in French will both resolve to "DE"). English names act as a fallback for all languages.

# Both of these are valid input
{"country": "NZ"}
{"country": {"code": "NZ", "name": "New Zealand"}}

Before releasing, you must add a changelog entry in the changes/ directory. Use the following format:

• With issue/PR number: echo "Your change description" > changes/123.bugfix.rst
• Without issue/PR (prefix with +): echo "Your change description" > changes/+20250104.misc.rst

Supported types: feature, bugfix, doc, removal, misc.

You can run all quality checks at once using just check. Alternatively, you can run individual tools directly using uv run.

Individual Tool Commands

• Formatting (import sorting + formatting):
  • Fix automatically: uv run ruff check --select I --fix django_countries
  • Format code: uv run ruff format django_countries
  • Check without changes: uv run ruff check --select I django_countries or uv run ruff format --check django_countries
• Linting:
  • uv run ruff check django_countries
  • Security scan: uv run bandit -r django_countries -x tests
• Type Checking:
  • uv run mypy django_countries

By default, multiple country fields render as a standard HTML multi-select dropdown. For a better user experience in the Django admin, you can use the FilteredSelectMultiple widget. This requires defining the field as a MultipleChoiceField in your form and overriding the field in the ModelAdmin.

from django import forms
from django.contrib import admin
from django.contrib.admin.widgets import FilteredSelectMultiple
from django_countries import countries
from myapp.models import Incident

class IncidentForm(forms.ModelForm):
    class Meta:
        model = Incident
        fields = '__all__'

    countries = forms.MultipleChoiceField(
        choices=list(countries),
        widget=FilteredSelectMultiple("Countries", is_stacked=False),
        required=False,
    )

@admin.register(Incident)
class IncidentAdmin(admin.ModelAdmin):
    form = IncidentForm

Basic Admin Integration

CountryField works automatically in the Django admin with a searchable dropdown. You can include it in list_display and search_fields (which supports searching by both code and name).

from django.contrib import admin
from myapp.models import Person

@admin.register(Person)
class PersonAdmin(admin.ModelAdmin):
    list_display = ['name', 'country']
    search_fields = ['name', 'country']