Skip to main content

Self-contained ISO 3166-1 country definitions.

Project description


Mike Spindel


ISO 3166-1 defines two-letter, three-letter, and three-digit country codes. python-iso3166 is a self-contained module that converts between these codes and the corresponding country name.


$ pip install iso3166


Country details

>>> from iso3166 import countries
>>> countries.get('us')
Country(name=u'United States', alpha2='US', alpha3='USA', numeric='840')
>>> countries.get('ala')
Country(name=u'\xc5land Islands', alpha2='AX', alpha3='ALA', numeric='248')
>>> countries.get(8)
Country(name=u'Albania', alpha2='AL', alpha3='ALB', numeric='008')

Country lists and indexes

>>> from iso3166 import countries

>>> for c in countries:
       print c
>>> Country(name=u'Afghanistan', alpha2='AF', alpha3='AFG', numeric='004')
Country(name=u'\xc5land Islands', alpha2='AX', alpha3='ALA', numeric='248')
Country(name=u'Albania', alpha2='AL', alpha3='ALB', numeric='008')
Country(name=u'Algeria', alpha2='DZ', alpha3='DZA', numeric='012')

>>> iso3166.countries_by_name
>>> {u'AFGHANISTAN': Country(name=u'Afghanistan', alpha2='AF', alpha3='AFG', numeric='004'),
u'ALBANIA': Country(name=u'Albania', alpha2='AL', alpha3='ALB', numeric='008'),
u'ALGERIA': Country(name=u'Algeria', alpha2='DZ', alpha3='DZA', numeric='012'),

>>> iso3166.countries_by_numeric
>>> {'004': Country(name=u'Afghanistan', alpha2='AF', alpha3='AFG', numeric='004'),
'008': Country(name=u'Albania', alpha2='AL', alpha3='ALB', numeric='008'),
'010': Country(name=u'Antarctica', alpha2='AQ', alpha3='ATA', numeric='010'),

>>> iso3166.countries_by_alpha2
>>> {'AD': Country(name=u'Andorra', alpha2='AD', alpha3='AND', numeric='020'),
'AE': Country(name=u'United Arab Emirates', alpha2='AE', alpha3='ARE', numeric='784'),
'AF': Country(name=u'Afghanistan', alpha2='AF', alpha3='AFG', numeric='004'),

>>> iso3166.countries_by_alpha3
>>> {'ABW': Country(name=u'Aruba', alpha2='AW', alpha3='ABW', numeric='533'),
'AFG': Country(name=u'Afghanistan', alpha2='AF', alpha3='AFG', numeric='004'),
'AGO': Country(name=u'Angola', alpha2='AO', alpha3='AGO', numeric='024'),


0.6 - September 28, 2014

  • Updated entries
    • Cabo Verde (changed in 2013-11)

  • Documented the dictionaries used for looking up countries by alpha2, etc. (thanks brunetton!)

0.5 - February 13, 2014

  • Added __contains__ to CountryLookup (thanks tomako!)

  • Current through ISO newsletter VI-16
    • No changes needed

0.4 - February 14, 2013

  • Current through ISO newsletter VI-14

  • Updated entries
    • Palestine

0.3 - September 4, 2012

  • Current through ISO newsletter VI-13

  • Fix changes from 0.2 (thanks vincentfretin!):
    • Venezuela

    • Saint Helena

    • Bolivia

0.2 - March 26, 2012

  • Current through ISO newsletter VI-12

  • Added missing entry for Afghanistan

  • Updated entries
    • Bolivia (ISO Newsletter VI-6)

    • Libya (VI-11)

    • Saint Helena (VI-7)

    • Sudan (VI-10)

    • Venezuela (VI-5)

  • New entries:
    • Bonaire, Sint Eustatius and Saba (VI-8)

    • Curaçao (VI-8)

    • Sint Maarten (Dutch part) (VI-8)

    • South Sudan (VI-10)

  • Deleted entries:
    • Netherlands Antilles (VI-8)

0.1 - December 14, 2010

  • Initial release

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distributions (10.7 kB view hashes)

Uploaded source

iso3166-0.6.tar.gz (7.7 kB view hashes)

Uploaded source

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page