ISO 639 Language Library

2.6.3 · active · verified Thu Apr 16

iso639-lang is a fast, comprehensive Python library for working with ISO 639 language codes and information. It provides access to language data across ISO 639-1, -2, and -3 standards. The library is actively maintained with frequent updates, often tied to new releases of the ISO 639-3 tables by SIL, and is currently at version 2.6.3.

Common errors

```
ImportError: cannot import name 'Lang' from 'iso639_lang'
```
cause Attempting to import from the PyPI package name (`iso639_lang`) instead of the actual module name (`iso639`).

fix Change your import statement to `from iso639 import Lang` (or other symbols like `languages`, `is_language`).
```
TypeError: Lang() takes 1 positional argument but 2 were given
```
cause You are passing multiple positional arguments to the `Lang` constructor, which is no longer supported since version 2.4.0. This might happen if you try to pass both a part1 and part3 code, for example.

fix Initialize `Lang` with only one positional argument (e.g., `Lang('eng')`) or by explicitly using a keyword argument for the specific part you're interested in (e.g., `Lang(part1='en')`).
```
TypeError: Lang() got an unexpected keyword argument 'name'
```
cause You are passing a generic keyword argument like 'name' to the `Lang` constructor, which is not supported since version 2.4.0. The constructor expects specific 'partX' keyword arguments or a single positional argument.

fix To look up by name, pass the name as a positional argument (e.g., `Lang('English')`). If you need to specify an ISO part, use `part1`, `part2b`, `part2t`, or `part3` as keyword arguments.
```
ValueError: 'bh' is not a valid ISO 639 identifier or name.
```
cause Attempting to create a `Lang` object for the `bh` (Bihari Languages) identifier, which has been deprecated by ISO and removed from the library's dataset.

fix Use specific ISO 639-3 codes for individual Bihari languages (e.g., `bho` for Bhojpuri) instead of the deprecated collective `bh` identifier.

Warnings

breaking Python 3.8 support was removed in version 2.6.0. Users on Python 3.8 or older will need to upgrade their Python interpreter or pin `iso639-lang` to `<2.6.0`.
Fix: Upgrade Python to 3.9 or newer. If unable, specify `iso639-lang<2.6.0` in your `requirements.txt` or `pyproject.toml`.
breaking The `Lang` constructor's argument handling changed significantly in v2.4.0. It no longer accepts multiple positional arguments (e.g., `Lang('eng', 'english')`) or arbitrary keyword arguments (e.g., `Lang(name='English')`). While v2.4.2 partially rolled back an unintended 'single positional argument' constraint, the general principle is to use one positional argument for an identifier/name, or one specific `partX` keyword argument.
Fix: Initialize `Lang` with a single positional argument (e.g., `Lang('eng')`) or a single `partX` keyword argument (e.g., `Lang(part1='en')`). Do not combine multiple identifiers or use non-specific keyword arguments like `name`.
deprecated The ISO 639-1 identifier `bh` for 'Bihari Languages' was deprecated by ISO and removed from the library's data files. While `iso639-lang` v2.5.0 explicitly marked it as deprecated, the data itself was updated in v2.4.0.
Fix: Avoid using `bh` as an identifier. For specific Bihari languages, use their respective ISO 639-3 codes (e.g., `bho` for Bhojpuri, `mai` for Maithili).
gotcha Accessing language information for performance: While `from iso639 import languages` provides a comprehensive list of `Lang` objects, iterating through it for lookup can be slow due to its size. For frequent lookups, consider pre-filtering or using `Lang('identifier')` directly, which leverages an optimized internal lookup.
Fix: For specific language lookups, prefer `Lang('your_identifier')`. Only iterate `languages` if you need to perform operations on the entire dataset or require filtering beyond direct identifier/name access.

Install

pip install iso639-lang Install stable release

Imports

Lang
wrong:
```
from iso639_lang import Lang
```
correct:
```
from iso639 import Lang
```
The PyPI package name is 'iso639-lang', but the top-level module is 'iso639'.
languages
```
from iso639 import languages
```
A pre-populated list of all Lang objects.
is_language
```
from iso639 import is_language
```
A utility function to validate language identifiers or names.

Quickstart

Demonstrates how to import the `Lang` class, create instances using various ISO 639 identifiers or English names, access language properties, and use the `is_language` validator. It also shows how to find a language from the pre-populated `languages` list.

from iso639 import Lang, languages, is_language

# Get a language by its identifier (ISO 639-1, -2, -3)
lang_en = Lang('en')
print(f"ISO 639-1: {lang_en.part1}, Name: {lang_en.name}")

lang_deu = Lang(part2b='deu') # Using specific part
print(f"ISO 639-2 (bibliographic): {lang_deu.part2b}, Name: {lang_deu.name}")

lang_ara = Lang('ara')
print(f"ISO 639-3: {lang_ara.part3}, Name: {lang_ara.name}, Scope: {lang_ara.scope}, Type: {lang_ara.type}")

# Find a language by its English name (case-insensitive)
lang_french = Lang('French')
print(f"French language: {lang_french.name} ({lang_french.part1})")

# Check if a string is a valid language identifier or name
print(f"'eng' is a language: {is_language('eng')}")
print(f"'invalidcode' is a language: {is_language('invalidcode')}")

# Iterate through all languages
# For performance, avoid loading all languages into memory if not needed
# for lang in languages:
#     if lang.part1 == 'es':
#         print(f"Found Spanish: {lang.name}")
#         break

view raw JSON →