---
id: isocodes
version: "2025.8.25"
license: GNU LESSER GENERAL PUBLIC LICENSE Version 2.1, February 1999 Copyright (C) 1991, 1999 Free Software Foundation, Inc. 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA Everyone is permitted… (full text in the JSON record)
license_treatment: permissive
maintenance: active
---

# isocodes — This project provides lists of various ISO standards (e.g. country, language, language scripts, and currency names) in one place

License: permissive · Maintenance: active · Downloads: 96.4K/mo

## 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 above — 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

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

- License: GNU LESSER GENERAL PUBLIC LICENSE Version 2.1, February 1999 Copyright (C) 1991, 1999 Free Software Foundation, Inc. 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA Everyone is permitted… (full text in the JSON record) (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 96.4K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

ISO country language currency codes, ISO 3166 ISO 639 ISO 4217 data, country code lookup library, language code reference data, ISO standards reference data, reference-data, iso-standards, cli-tool

[View on SkillFed](https://skillfed.io/packages/isocodes) · [View on PyPI](https://pypi.org/project/isocodes/)