django-countries

Features

• Add django_countries.django_filters.CountryFilter for django-filters integration with support for custom empty_label. This filter automatically sets country choices and seamlessly integrates with django-filters FilterSets, making it easier to add country filtering to your views. (#307)

• Enable CountryFieldMixin to accept name_only, country_dict, and output customization options via Meta.extra_kwargs. You can now configure country field serialization behavior without explicitly declaring serializer fields, making it easier to customize output for both single and multiple country fields. (#414)

• CountryField(country_dict=...) now accepts either a boolean (existing behaviour) or an iterable/string of keys so you can control exactly which values appear in the serialized country dict (for example ("code", "name", "alpha3") or just "alpha3"). (#416)

• Add COUNTRIES_FIRST_BY_LANGUAGE and COUNTRIES_FIRST_AUTO_DETECT settings for dynamic country ordering based on user language. Countries can now be automatically reordered based on the current language, with locale-based auto-detection (e.g., fr-CA users see Canada prepended to the French country group). (#418)

• Add support for custom flag_url in COUNTRIES_OVERRIDE setting. You can now specify a custom flag URL for overridden countries:

  COUNTRIES_OVERRIDE = {
      "IND": {
          "names": ["Indonesia"],
          "ioc_code": "INA",
          "flag_url": "flags/id.gif",
      },
  }
  

  This is particularly useful when using custom country codes that need to reference existing flag images. (#449)

• Add countries_context() context manager for temporary, thread-local override of country configuration options. Supports all country options (first, only, first_sort, first_repeat, first_break, first_by_language, first_auto_detect), enabling per-request customization based on user preferences, IP geolocation, or other dynamic factors. Each option independently overrides its corresponding setting with the highest priority.

Bugfixes

• Fix CountryField serializer to respect current language when deserializing localized country names. The field now automatically uses Django's get_language() to detect the active language and falls back to English if the country name is not found in the current language. (#407)
• Fixed CountryFilter to support filtering on CountryField through relations (e.g., list_filter = [("contact__country", CountryFilter)]). Previously this would fail with a FieldError. (#432)
• Fixed CountryFilter admin filter to work correctly with CountryField(multiple=True). The filter now uses the __contains lookup instead of exact matching to properly find records where the selected country appears in the comma-separated country list. (#445)
• Added support for empty_label parameter in CountryField.formfield() to customize the blank choice label in form fields. This allows using empty_label="" for an empty label or empty_label="Custom text" for custom text, resolving the issue where empty_label was previously ignored. (#466)
• Fixed type annotation for CountryField.countries parameter in stub file to accept type[Countries] instead of Countries instance, resolving mypy errors when using custom Countries subclasses. Also removed unnecessary exclusion of tests from mypy checking. (#482)

Misc

• Refactored deployment script from bash (244 lines) to Python using click for better maintainability and testability. The script is now in scripts/deploy.py with these improvements:

  • Interactive mode: Run just deploy without arguments to get an interactive prompt showing version options (e.g., "8.1.1 → 8.2.0")
  • Enhanced dry-run: DRY_RUN=1 now validates package builds, documentation builds, runs pre-commit checks, shows full changelog preview, checks PyPI for existing versions, displays translation status, and checks for uncommitted changes (same as real run)
  • Comprehensive summary: Shows a detailed list of completed steps at the end of each run
  • Allow dirty: --allow-dirty flag to bypass git status check when needed (not recommended for production)
  • Better error handling: Clear error messages with proper exception types
  • Colorful output: Uses click's styling for better readability

Bugfixes

• Fixed CountryField(multiple=True) not marking selected options in Django forms. (#480)

Features

• DRF serializer fields now respect the allow_null parameter, returning None for NULL values when allow_null=True. This enables better API consistency and is particularly useful with unique=True constraints, which allow multiple NULL values but not multiple empty strings in the database. (#453)
• Add support for null=True on multiple country fields, allowing This nullable unique constraints on multiple country fields. CountryField(multiple=True, null=True) now returns None for NULL database values instead of crashing and the historical system check E100 that blocked multiple=True + null=True has been removed. (#453)

Bugfixes

• Fixed OpenAPI schema generation for CountryField when using country_dict=True or name_only=True. The field now correctly generates an object schema (with code and name properties) for country_dict=True and a string schema for name_only=True, instead of incorrectly generating an enum schema. This fixes schema generation for both DRF's built-in OpenAPI support and drf-spectacular, enabling accurate TypeScript client generation and other API tooling. (#441)
• Major performance enhancement for Django admin. Added per-language caching to Countries.__iter__(), delivering 20-40× speedup when displaying CountryField in list_display (admin changelist now renders in <0.5s instead of 6-10s). (#454)
• Fixed a regression where a country field allowing for selection of multiple countries could not be added to using the + operator. (#455)

Bugfixes

• Fixed required attribute not being rendered on form widgets when using COUNTRIES_FIRST_BREAK setting. The separator option now correctly allows the field to remain required for HTML5 validation. (#280)
• Fixed Transifex translation pull workflow to use git commit timestamps instead of filesystem modification times, preventing translations from being incorrectly skipped. Updated German (de), Afrikaans (af), Slovak (sk), and Slovenian (sl) translations.

Misc

• Add OLD_NAMES for Bahamas and Netherlands to support translation fallback when country names change. Updated translation workflow to generate English source locale and automatically push to Transifex during releases.

Note: This release includes all changes from the yanked versions 7.8, 7.9, and 7.9.1, which were yanked because they inadvertently dropped Python 3.7 support without a major version bump.

Features

• Added common names for six additional countries/territories: Democratic Republic of the Congo (CD), South Georgia (GS), Netherlands (NL), Palestine (PS), Saint Helena (SH), and Vatican City (VA). These provide friendlier, shorter names when COUNTRIES_COMMON_NAMES is enabled (default).

Bugfixes

• Fix COUNTRIES_OVERRIDE to support custom country codes that are 3 characters long. Previously, 3-character codes were incorrectly treated as alpha3 codes and resolved to existing countries. (#474)
• Fixed TypeError "unhashable type: 'list'" when using CountryField(multiple=True) in Django admin list_display. (#311)
• Fixed CountryField(multiple=True) displaying "-" instead of country names in Django admin readonly_fields. (#463)
• Fixed incorrect max_length calculation for CountryField(multiple=True) when using COUNTRIES_FIRST with COUNTRIES_FIRST_REPEAT. (#469)
• Updated country names to match ISO 3166-1 OBP: Bahamas (The) and Netherlands (Kingdom of the). Also improved self_generate() regex to handle type hints in dictionary declarations.

Improved Documentation

• Added MkDocs documentation site and simplified README to focus on quick start with link to full documentation.
• Consolidated release documentation into CONTRIBUTING.md and improved development setup instructions.
• Added documentation warning that CountryField does not support Django's autocomplete_fields in admin or third-party admin filter packages like more_admin_filters. (#473)
• Added comprehensive documentation on ISO 3166-1 country name formatting, explaining parentheses vs commas usage, capitalization of "the", and addressing common political objections about territories like Taiwan, Kosovo, Hong Kong, and Palestine.

Deprecations and Removals

• Drop Python 3.7 support. Python 3.7 reached end-of-life in June 2023. The minimum supported Python version is now 3.8.

Misc

• Expanded test matrix to cover Python 3.8-3.13 and Django 3.2-5.1 with improved test infrastructure.
• Fixed various code quality issues identified by ruff linter, including improved string formatting and file handling.
• Migrated build system from setuptools to uv_build for faster and more modern package building.
• Simplified release process with automated just deploy command and towncrier for changelog management.
• Fix unnecessary list comprehension in test_tags.py

Bugfixes

• Fix COUNTRIES_OVERRIDE to support custom country codes that are 3 characters long. Previously, 3-character codes were incorrectly treated as alpha3 codes and resolved to existing countries. (#474)

Note: This release was yanked because it inadvertently dropped Python 3.7 support without a major version bump. Use 8.0.0 or later instead.

Bugfixes

• Fixed TypeError "unhashable type: 'list'" when using CountryField(multiple=True) in Django admin list_display. (#311)
• Fixed CountryField(multiple=True) displaying "-" instead of country names in Django admin readonly_fields. (#463)
• Fixed incorrect max_length calculation for CountryField(multiple=True) when using COUNTRIES_FIRST with COUNTRIES_FIRST_REPEAT. (#469)

Note: This release was yanked because it inadvertently dropped Python 3.7 support without a major version bump. Use 8.0.0 or later instead.

Where'd 7.7 go? Well 7.6 was accidentally bumped to 7.8 because of the new release process!

Note: This release was yanked because it inadvertently dropped Python 3.7 support without a major version bump. Use 8.0.0 or later instead.

Improved Documentation

• Added MkDocs documentation site and simplified README to focus on quick start with link to full documentation.
• Consolidated release documentation into CONTRIBUTING.md and improved development setup instructions.

Misc

• Expanded test matrix to cover Python 3.8-3.13 and Django 3.2-5.1 with improved test infrastructure.
• Fixed various code quality issues identified by ruff linter, including improved string formatting and file handling.
• Migrated build system from setuptools to uv_build for faster and more modern package building.
• Simplified release process with automated just deploy command and towncrier for changelog management.

• Fix a TypeError when no country is selected, introduced in the Django 5 fix.

• 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.

• Fix error when using USE_I18N = False.

• Fix broken translations due to last common country names fix.

• 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+).

• 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.

• Typing compatibility fixes for Python <3.9.

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

• Fix Latin translations.

• 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).

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

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

• Add a GraphQL object type for a django 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.

• Add test coverage for Django Rest Framework 3.9.

• Tests for Django 2.1 and Django Rest Framework 3.8.

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

• 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.

• 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).

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

• 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).

• 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.

• Use transparency layer for flag sprites.

• Fix invalid reStructuredText in CHANGES.

• 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.

• Add sprite flag files (and 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!

• Fix minor packaging error.

• 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.

• Packaging fix (CHANGES.rst wasn't in the manifest)

• 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.

• Fix CountrySelectWidget failing when used with a model form that is passed a model instance.

• Revert descriptor to always return a Country object.

• Fix the CountryField widget choices appearing empty due to a translation change in v3.0.

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)

• Fix Python 3 compatibility.

• Fix issue with translations getting evaluated early.

• Add IOC (3 letter) country codes.

• Fix bug when loading fixtures.