num2words

library0.5.14pypypi✓ verified 24d ago

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.

data

pip install num2words

github ↗package ↗

INSTALL

IMPORT

SIG · NUM2WORDS

num2words

datapythonv0.5.14

Install

2.6s avg

Import

71ms

Disk

18MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.5.14 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.072s · 20.4MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 2.6s · import 0.070s · 21MB

18MB installed

● package 18MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

num2words

✓ from num2words import num2words

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

num2words --version

Debug

Known issues

breakingThe `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'`.

affects: <=0.5.x (prior to comprehensive `to` argument)

breakingPyPI 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.

affects: 0.5.15, 0.5.16

gotchaAttempting 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.

affects: All versions

gotchaWhile `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.

affects: All versions

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'num2words'

This error occurs when the `num2words` library has not been installed in your Python environment or is installed in a different environment than the one you are currently using.

fix

Install the library using pip:
`pip install num2words`

If you have multiple Python versions, you might need to use `pip3 install num2words` or ensure you activate the correct virtual environment before installation.

AttributeError: 'module' object has no attribute 'num2words'

This error arises when you import the entire `num2words` module using `import num2words` and then try to call `num2words(number)` directly. The module itself is not a callable function.

fix

You need to access the `num2words` function from within the imported module, or import the function directly:

Option 1 (recommended): Import the function directly:
`from num2words import num2words
word_representation = num2words(42)`

Option 2: Access the function through the module:
`import num2words
word_representation = num2words.num2words(42)`

TypeError: type(<input>) not in [long, int, float] (or similar TypeError for invalid input)

The `num2words` function expects a numerical input (integer or float). This `TypeError` occurs when a non-numeric type, such as a string that cannot be implicitly converted to a number, a list, or an object, is passed as the primary argument.

fix

Ensure that the value you pass to `num2words()` is an integer or a float. If you have a string representation of a number, convert it first:
`number_str = '123'
word_representation = num2words(int(number_str))`

Or for a float:
`float_str = '123.45'
word_representation = num2words(float(float_str))`

NotImplementedError

This error is raised when you specify a `lang` (language) argument that is not supported by the installed version of `num2words`.

fix

Check the official `num2words` documentation or GitHub repository for the list of currently supported language codes. If the desired language is not supported, you may need to fallback to a supported language or contribute the missing language.

Example of handling:
`try:
    word = num2words(100, lang='unsupported_lang_code')
except NotImplementedError:
    word = num2words(100, lang='en') # Fallback to English`

Upgrade

Version history

0.5.14latest on PyPI · released Dec 17, 2024

Audit

Dependencies

docoptoptionalUsed for the command-line interface (CLI) utility. Not strictly required for programmatic library usage.

Agent activity

11 hits · last 30 days

node

Resources

githubhttps://github.com/savoirfairelinux/num2words ↗

packagehttps://pypi.org/project/num2words/ ↗