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](https://github.com/SmileyChris/django-countries/issues/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](https://github.com/SmileyChris/django-countries/issues/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](https://github.com/SmileyChris/django-countries/issues/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](https://github.com/SmileyChris/django-countries/issues/418))
- Add support for custom `flag_url` in `COUNTRIES_OVERRIDE` setting. You can now specify a custom flag URL for overridden countries:

python
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](https://github.com/SmileyChris/django-countries/issues/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](https://github.com/SmileyChris/django-countries/issues/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](https://github.com/SmileyChris/django-countries/issues/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](https://github.com/SmileyChris/django-countries/issues/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](https://github.com/SmileyChris/django-countries/issues/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](https://github.com/SmileyChris/django-countries/issues/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](https://github.com/SmileyChris/django-countries/issues/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](https://github.com/SmileyChris/django-countries/issues/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](https://github.com/SmileyChris/django-countries/issues/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](https://github.com/SmileyChris/django-countries/issues/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](https://github.com/SmileyChris/django-countries/issues/454))
- Fixed a regression where a country field allowing for selection of multiple countries could not be added to using the + operator. ([455](https://github.com/SmileyChris/django-countries/issues/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](https://github.com/SmileyChris/django-countries/issues/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](https://github.com/SmileyChris/django-countries/issues/474))
- Fixed TypeError "unhashable type: 'list'" when using CountryField(multiple=True) in Django admin list_display. ([311](https://github.com/SmileyChris/django-countries/issues/311))
- Fixed CountryField(multiple=True) displaying "-" instead of country names in Django admin readonly_fields. ([463](https://github.com/SmileyChris/django-countries/issues/463))
- Fixed incorrect max_length calculation for CountryField(multiple=True) when using COUNTRIES_FIRST with COUNTRIES_FIRST_REPEAT. ([469](https://github.com/SmileyChris/django-countries/issues/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](https://github.com/SmileyChris/django-countries/issues/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](https://github.com/SmileyChris/django-countries/issues/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.