Num2Words

0.5.14 · active · verified Thu Apr 09

Num2Words is a Python library designed to convert numerical values into their word representations across multiple languages. It supports various output formats, including cardinal numbers (e.g., 'forty-two'), ordinal numbers (e.g., 'forty-second'), years, and currency representations with appropriate localization. The library is currently active, with the latest stable version being 0.5.14, and receives regular updates, primarily focusing on adding new language support and fixing existing localizations.

Warnings

breaking The `ordinal` boolean argument (e.g., `num2words(42, ordinal=True)`) was replaced by the `to` argument with values like `'ordinal'` or `'ordinal_num'` in later 0.5.x versions. Using the old `ordinal=True` may lead to unexpected behavior or errors in current versions.
Fix: Replace `ordinal=True` with `to='ordinal'` or `to='ordinal_num'`.
breaking PyPI versions 0.5.15 and 0.5.16 of `num2words` were compromised with 'Scavenger Malware' in July 2025 due to a phishing attack on maintainers. These versions contained malicious code and were removed from PyPI. **Do not install or use these specific versions.**
Fix: Ensure you are using a safe version (e.g., 0.5.14 or earlier safe versions). If you installed 0.5.15 or 0.5.16, downgrade immediately and audit your systems for compromise.
gotcha Attempting to convert a number to a language that is not supported will raise a `NotImplementedError`.
Fix: Implement a fallback mechanism, such as a `try-except NotImplementedError` block, to default to English or another supported language if the requested language is unavailable.
gotcha While `num2words` supports many languages, some language localizations, particularly for ordinal numbers or complex grammatical rules (e.g., Arabic, Korean, Amharic), may still contain bugs or inaccuracies.
Fix: Review the output for critical applications, especially when using less common languages or complex number formats. Check GitHub issues for known language-specific problems.

Install

pip install num2words Install latest stable version

Imports

num2words
```
from num2words import num2words
```

Quickstart

This quickstart demonstrates how to import the `num2words` function and use it for various conversion types, including cardinal, ordinal, ordinal number, and currency formats, as well as specifying a target language.

from num2words import num2words

# Basic cardinal conversion (default)
print(num2words(42)) # forty-two

# Ordinal conversion
print(num2words(42, to='ordinal')) # forty-second

# Ordinal number conversion
print(num2words(42, to='ordinal_num')) # 42nd

# Currency conversion (defaults to 'dollar' or 'euro' based on language)
print(num2words(1234.56, to='currency', currency='USD')) # one thousand, two hundred and thirty-four dollars, fifty-six cents

# French language conversion
print(num2words(42, lang='fr')) # quarante-deux

view raw JSON →