{"id":2927,"library":"django-countries","title":"Django Countries","description":"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.","status":"active","version":"8.2.0","language":"en","source_language":"en","source_url":"https://github.com/SmileyChris/django-countries/","tags":["django","countries","flags","forms","models","i18n","geography"],"install":[{"cmd":"pip install django-countries","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Core functionality is built on Django models and forms.","package":"Django","optional":false}],"imports":[{"note":"`CountryField` is located in the `django_countries.fields` submodule, not directly under `django_countries`.","wrong":"from django_countries import CountryField","symbol":"CountryField","correct":"from django_countries.fields import CountryField"},{"note":"The `countries` object (an iterable of ISO 3166-1 country codes and names) is available directly from the `django_countries` package.","wrong":"from django_countries.fields import countries","symbol":"countries","correct":"from django_countries import countries"}],"quickstart":{"code":"# settings.py\nINSTALLED_APPS = [\n    # ...\n    'django_countries',\n]\n\n# models.py (in your app)\nfrom django.db import models\nfrom django_countries.fields import CountryField\n\nclass Person(models.Model):\n    name = models.CharField(max_length=100)\n    country = CountryField()\n\n# Example usage in a Django shell\n# >>> from myapp.models import Person\n# >>> person = Person.objects.create(name=\"Chris\", country=\"NZ\")\n# >>> person.country\n# Country(code='NZ')\n# >>> person.country.name\n# 'New Zealand'\n# >>> person.country.flag\n# '/static/flags/nz.gif'","lang":"python","description":"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`."},"warnings":[{"fix":"Upgrade Python to 3.8+ or pin `django-countries<8.0.0`.","message":"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.","severity":"breaking","affected_versions":">=8.0.0"},{"fix":"Ensure correct Python dictionary syntax for `COUNTRIES_OVERRIDE` to prevent parsing errors. Example: `COUNTRIES_OVERRIDE = {'EU': {'names': ['European Union'], 'alpha3': 'EUN', 'numeric': 998}}`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Evaluate your geographical data requirements. If beyond just countries, explore `django-cities-light` or `django-cities` for more comprehensive solutions.","message":"`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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Explicitly access the desired attribute (e.g., `.name`, `.code`, `.flag`) when working with `Country` objects in your code and templates.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}