Django Countries

8.2.0 · active · verified Sat Apr 11

django-countries is a Django application that provides a `CountryField` for models, offering all ISO 3166-1 countries as choices. It includes utilities for forms, flag icons as static files, and integrates with Django's internationalization system for translated country names. The current version is 8.2.0, and it maintains an active release cadence with regular updates.

Warnings

breaking Version 8.0.0 inadvertently dropped Python 3.7 support without a major version bump, leading to yanked releases. Users on Python 3.7 should use a version prior to 8.0.0 or upgrade their Python environment.
Fix: Upgrade Python to 3.8+ or pin `django-countries<8.0.0`.
gotcha When overriding country definitions using `COUNTRIES_OVERRIDE` in `settings.py`, be careful with dictionary syntax, particularly trailing commas which can cause unexpected issues or silent failures depending on Python version and context.
Fix: Ensure correct Python dictionary syntax for `COUNTRIES_OVERRIDE` to prevent parsing errors. Example: `COUNTRIES_OVERRIDE = {'EU': {'names': ['European Union'], 'alpha3': 'EUN', 'numeric': 998}}`.
gotcha `django-countries` is designed specifically for managing country selections. For more complex geographical data, such as cities, regions, or subregions, consider using dedicated libraries like `django-cities-light` or implementing a custom solution.
Fix: Evaluate your geographical data requirements. If beyond just countries, explore `django-cities-light` or `django-cities` for more comprehensive solutions.
gotcha When retrieving a `CountryField` value, it returns a `Country` object. To access the full country name or other attributes, use `instance.country.name` or `instance.country.code`. Simply using `instance.country` in some contexts (like template forms without explicit rendering) might default to displaying the country code.
Fix: Explicitly access the desired attribute (e.g., `.name`, `.code`, `.flag`) when working with `Country` objects in your code and templates.

Install

pip install django-countries Install stable version

Imports

CountryField
```
from django_countries.fields import CountryField
```
`CountryField` is located in the `django_countries.fields` submodule, not directly under `django_countries`.
countries
```
from django_countries import countries
```
The `countries` object (an iterable of ISO 3166-1 country codes and names) is available directly from the `django_countries` package.

Quickstart

To get started, add `django_countries` to your `INSTALLED_APPS` in `settings.py`. Then, import `CountryField` from `django_countries.fields` and use it in your Django models. This will provide a dropdown with all ISO 3166-1 countries in forms and the admin. Accessing the field on an instance returns a `Country` object with properties like `name` and `flag`.

# settings.py
INSTALLED_APPS = [
    # ...
    'django_countries',
]

# models.py (in your app)
from django.db import models
from django_countries.fields import CountryField

class Person(models.Model):
    name = models.CharField(max_length=100)
    country = CountryField()

# Example usage in a Django shell
# >>> from myapp.models import Person
# >>> person = Person.objects.create(name="Chris", country="NZ")
# >>> person.country
# Country(code='NZ')
# >>> person.country.name
# 'New Zealand'
# >>> person.country.flag
# '/static/flags/nz.gif'

view raw JSON →