isocodes

What it is and what it does

isocodes is a reference-data library that bundles ISO standard lists (countries, languages, currencies, scripts, subdivisions, and former countries) into a single Python package with modern access patterns. Instead of maintaining your own CSV or JSON files of country codes and names, you import isocodes and query structured data via dot notation (usa.name, usa.flag) or dictionary access, with fast lookup methods like find() for O(1) exact matches and search() for flexible filtering. The data originates from the Debian iso-codes project.

The library is zero-dependency and includes both a Python API and a command-line interface for quick lookups. It supports Python 3.9 through 3.13 and is actively maintained. Common use cases include populating country/language dropdowns, validating ISO codes in user input, and building geographic or linguistic metadata into applications.

Use it for:

• Populate country or language selection dropdowns in web forms with canonical names and codes
• Validate user-supplied ISO codes (alpha-2, alpha-3, numeric) against authoritative reference data
• Build geographic metadata (flags, official names, subdivisions) into location-aware applications
• Generate reports or exports in CSV/JSON with standardized currency or language codes
• Look up historical country names (e.g., 'Burma' → Myanmar) for data reconciliation
• CLI tool for quick ad-hoc ISO code lookups without writing Python code

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

isocodes provides programmatic access to ISO standard reference data (countries, languages, currencies, scripts, subdivisions) with dot-notation object access and fast lookup methods.

Yes. Zero dependencies, permissive license, active maintenance, no known vulnerabilities, and a clear use case for any application needing canonical ISO reference data. Install if you need to work with country codes, language codes, or related ISO standards; skip only if you maintain your own reference data or have very specific non-standard requirements.

Install

isocodes on PyPI

pip install isocodes

uv add isocodes

poetry add isocodes

Installing isocodes

Before you install

No runtime dependencies and low install friction. Active maintenance with recent release (2025-08-25) and a commit history through 2026-06-22.

License in practice

Licensed under LGPL 2.1 (permissive). You may use and modify the library freely; if you distribute modified versions, you must provide source code and license notice, but you can link it into proprietary applications.

Quickstart

pip install isocodes

from isocodes import countries
usa = countries.find(alpha_2="US")
print(usa.name)  # 'United States'
print(usa.flag)  # '🇺🇸'

Verify before relying

• Whether the data is updated regularly to reflect ISO standard changes and country name/code updates
• Performance characteristics of search() method on large result sets
• Completeness of coverage for all ISO 639-3 and ISO 639-5 language codes

Package facts

Evidence: isocodes-2025.8.25-py3-none-any.whl

Keywords: iso

Tags

More Utilities packages