NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
PyPI · #578 most downloaded on PyPI
ISO country, subdivision, language, currency and script definitions and their translations
Last release 7 months ago
17 Feb 2026
Release timing varies
gaps range from 5 weeks to 1.8 years
Some releases are documented
notes for 21 of the last 60 stable releases
Nothing withdrawn
no release was ever pulled
18 years old
64 releases · first in 2008
Merge pull request #297 from zware/bump_for_release
Merge pull request #297 from zware/bump_for_release
Bump version for release
Dropped support for end-of-life Pythons 3.8 and 3.9.
Added explicit support for Python 3.13 and 3.14.
Updated to iso-codes 4.20.1.
Added support for matching initials in countries.search_fuzzy. For
example, results for countries.search_fuzzy("UK") will now include
GB (United Kingdom).
Fixed subdivisions.add_entry and subdivisions.remove_entry, which
would previously render the country_code index of subdivisions
unusable causing subdivisions.get(country_code=...) to return a malformed
result. Fixes issue #281.
One column per quarter.
Breaking change: Reverted the fallback to name when country common_name or official_name attributes not available, which was added in 23.12.11.
Breaking change: Reverted the fallback to name when country common_name or official_name attributes not available, which was added in 23.12.11.
Fixed import of importlib_metadata to importlib.metadata
Fixed bug causing parent subdivision codes to be returned with additional country code preceding (i.e. GB-GB-ENG instead of GB-ENG)
Update to iso-codes 4.16.0. (Thanks to musicinmybrain!)
~~Added fallback to name when common_name or official_name country attributes are missing~~ Reverted in v24.6.1.
Added fallback to name when common_name or official_name country attributes
are missing Reverted in v24.6.1.
Added support for adding and removing country records, as well as casting to dict
Improve performance speed by checking for non-ascii chars before removing accents
Added search_fuzzy method to subdivisions
Added type hinting, created py.typed file, and added mypy checks to CI
Dropped support for end-of-life Python 3.6 and 3.7.
Dropped support for end-of-life Python 3.6 and 3.7.
Added support for Python 3.11 and Python 3.12.
Added dependency on importlib-resources for Python 3.8.
Dropped implicit dependency on setuptools for pkg_resources. (Thanks to D3X!)
Update to iso-codes 4.15.0. (Thanks to alanorth!)
Removes iso3166.mo files and opts for newer iso3166-1.mo and iso3166-3.mo files for Country and Historic Country Translations respectively.
Warning: This requires an update in your application code when you previously used to access the iso3166 gettext data.
- Update to iso-codes 4.9.0.
Update to iso-codes 4.8.0. (Thanks to llimeht!)
Fix bug #37: (accidental) unconditional pkg_resources import. (thanks, crbunney)
Add (auto-generated) __version__ attribute to the main module. (Fixes issue #4)
Add (auto-generated) version attribute to the main module. (Fixes issue #4)
Add fuzzy search to historic countries. (Fixes issue #26)
Update to iso-codes 4.5.0.
PR 9: Clean up the normalization (lower casing) of values in indexes and searches. See PR https://github.com/flyingcircusio/pycountry/pull/9 for detailed discussion. This also fixed issue #8.
Smaller cleanups and build environment version bumps.
PR 35: Python 3-only cleanups and updated Python minor version compatibility (thanks, Djailla)
PR 33: Remove defunct bugtracker link from README (thanks, jwilk)
PR 32: (Somewhat hilarious) Typo (thanks, jwilk)
Moved to Git/Github; switched from Bitbucket Pipelines to Travis builds.
Preparing release 19.8.18
Preparing release 19.8.18
Fix installation on systems that don't have UTF-8 as default encoding. (#13422)
Remove superfluous print debugging output. (#13424)
Preparing release 19.7.15
Preparing release 19.7.15
Update to iso-codes 4.3.
Add support for ISO 639-5 (Language Families and Groups).
Drop support for Python 2.
Add search_fuzzy() function to the countries database. This allows
for dealing with user searches that aren't really aware of ISO 3166 (so,
like, actual human beings). A bit of character normalization and prioritizing
matches between multiple criteria allows building somewhat reasonable
suggestion/autocompletion lists. (#13418)
Caveat emptor: no attention has been paid to performance in this feature.
Switch API from "get + KeyError" to " get + default=None". This is a subtle API-breaking change. Please update carefully.
WARNING: This release contains a subtle but important API change that may break integrations!
Looking at #13416 I realized that I made a terrible API design choice with
respect to how the get function should behave in Python. Probably under the
influence of either too little or too much whiskey I went and implemented get
so that it raises a KeyError instead of doing the Pythonic thing and returning
None and allowing to customize the default. There was a bit of back-and-forth
around this code in previous releases (specifically touching edge cases to
have the Subdivision API behave "reasonably", although there doesn't seem
to be one right way there.)
Anyway, when preparing this release and reviewing #13416 and the other related issues and changes from the past I noticed my mistake an decide to fix it going forward.
So, from now on get will behave as expected in Python and yes, this means
you will have to update your integration code carefully now checking for
None returns instead of expecting KeyErrors. This is work, but I think it's
worthwhile to uphold this convention within the Python community.
Switch API from "get + KeyError" to " get + default=None". This is a subtle API-breaking change. Please update carefully. (#13416)
Update to iso-codes 4.1.
Fix #13394: incorrect KeyError shadowing in Subdivisions.get()
- Update to iso-codes 3.79.
- Update to iso-codes 3.78.
Update to iso-codes 3.76, which fixes #13398.
Update to iso-codes 3.75, which fixes #13389 again. (bad parent codes for GB).
Update to iso-codes 3.75, which fixes #13389 again. (bad parent codes for GB).
Switch from building on drone.io (discontinued service) to bitbucket's Pipelines.
Update pytest dependencies to get rid of API warnings.
Update to iso-codes 3.73, which fixes #13389 (bad parent codes for CZ).
Return empty lists from the subdivision database if the country exists but does not have any subdivisions. Fixes #13374.
Return empty lists from the subdivision database if the country exists but does not have any subdivisions. Fixes #13374.
Some typo fixes. Thanks to @VictorMireyev.
Update to iso-codes-3.72.
16.11.27 was a brown bag release. I merged the PRs online, but didn't pull them. Well. This is what 16.11.27 actually should have been.
Fix encoding issue on Python 3 (which seems to have been limited to some platforms.) Via PR17, fixes #13386. Thanks to @masroore and @hiaselhans.
Fix encoding issue on Python 3 (which seems to have been limited to some platforms.) Via PR17, fixes #13386. Thanks to @masroore and @hiaselhans.
Documentation fix: iso639_1_code is not a valid key for languages any more. Fixes #13387, thanks to @jmitzka.
Update to iso-codes-3.71.
This release was heavily supported by @zware who fixed some of the issues I overlooked in the last releases and a few enhancements.
This release was heavily supported by @zware who fixed some of the issues I overlooked in the last releases and a few enhancements.
All data objects now have a repr() that includes all values. (@zware)
All database objects now have a lookup method that takes a value and returns the first data object that has an attribute that matches the value. Note that searching is halted when the first match is found. (@zware)
Clean up historical countries: the deleted flag is gone and there is no database that holds both historical and present countries any longer. The record formats are too different to keep this facade up reasonably well.
Fix parent lookup for subdivisions.
Update README to correctly show the updated field names.
Update pins for the packages we depend on.
Reduce Python test coverage to Python 2.7 and 3.5 -- I can't sustain running a bazillion Python versions all the time forever.
Fix Python 3 compatibility (@zware)
Incorporate some typos and suggested README improvements from @Pander in
Adapt README to the new attributes.
This is a major change. The upstream packages have been revamped from the former XML databases to use JSON. They adapted their schemata a bit and thus
This is a major change. The upstream packages have been revamped from the former XML databases to use JSON. They adapted their schemata a bit and thus made some of the structures in pycountry superfluous (yay!). Memory usage went down when all databases are loaded (32.7 MiB down from 83.6 MiB) and performance has gone up (not measured scientifically, but it's noticeable when loading the DBs in an interactive session).
To mark this major change, I'm also switch from the existing (not useful) SemVer-based version numbers to CalVer-based numbers using YY.MM.DD.micro as the pattern.
To avoid adding more complexity I have removed code that really only was necessary because of the complexity of using the XML databases.
Here's what you need to know:
I updated to iso-codes 3.70 which is a lot fresher than the last release.
Attribute names have changed. There is no longer a mapping going on between the sources and the object attributes. Take a look at the JSON files (or inspect the objects) to see which fields are supported.
You can also inspect the automatically build indexes (db.indices) to see all keys in a database. Not every object supports every attribute - this depends on the quality of the data from pkg-isocodes.
Attribute names are more coherent now, too. Note that "alpha2", "alpha4", etc. are now using an underscore as that's the pattern in the upstream packages. So it's "alpha_2" now.
HistoricCountries no longer includes countries that still exist. I removed the computed fields that were meant to make it easy to filter.
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Your coding agent can read these notes before it upgrades. Set up the MCP server →