Registry / web-framework / django-countries

django-countries

library9.0.0pypypi✓ verified 25d ago

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.

web-framework database

pip install django-countries

github ↗package ↗

INSTALL

IMPORT

SIG · DJANGO-COUNTRIES

django-countries

web-frameworkpythonv9.0.0

Install

1.8s avg

Import

—

Disk

28MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v9.0.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.000s · 22.3MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.8s · import 0.000s · 23MB

28MB installed

● package 28MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

CountryField

✓ from django_countries.fields import CountryField

✗ from django_countries.fields import CountryField

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'

Debug

Known issues

breakingVersion 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`.

affects: >=8.0.0

gotchaWhen 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}}`.

affects: All versions

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.

affects: All versions

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

affects: All versions

Upgrade

Version history

9.0.0latest on PyPI · released Jun 10, 2026

Audit

Dependencies

DjangorequiredCore functionality is built on Django models and forms.

Agent activity

12 hits · last 30 days

node

Resources

githubhttps://github.com/SmileyChris/django-countries ↗

packagehttps://pypi.org/project/django-countries/ ↗