Install & Compatibility
Where this runs
tested against v4.1.0 · 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
muslpy 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 0.000s · 65.5MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 1.6s · import 0.000s · 18MB
65MB installed
● package 65MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
RomanNumeral
✓ from roman_numerals import RomanNumeral
✗ from roman_numerals_py import RomanNumeral
The underlying library is named `roman-numerals`, which is the correct import path even for versions of `roman-numerals-py` prior to it becoming a meta-package. As of v4.0.0, `roman-numerals-py` is a meta-package for `roman-numerals`.
InvalidRomanNumeralError
✓ from roman_numerals import InvalidRomanNumeralError
Exceptions are also imported from the `roman_numerals` package.
OutOfRangeError
✓ from roman_numerals import OutOfRangeError
Exceptions are also imported from the `roman_numerals` package.
This quickstart demonstrates basic conversion from integers to Roman numerals and vice-versa, as well as handling invalid input. It uses the `RomanNumeral` class from the `roman_numerals` package, which is the underlying library for `roman-numerals-py`.
from roman_numerals import RomanNumeral, InvalidRomanNumeralError, OutOfRangeError
# Create a RomanNumeral from an integer
num_from_int = RomanNumeral(16)
print(f"Integer 16 as Roman: {num_from_int}") # Expected: XVI
# Create a RomanNumeral from a string
num_from_string = RomanNumeral.from_string("XVI")
print(f"Roman 'XVI' as Integer: {int(num_from_string)}") # Expected: 16
# Convert to uppercase/lowercase
print(f"'XVI' uppercase: {num_from_string.to_uppercase()}")
print(f"'XVI' lowercase: {num_from_string.to_lowercase()}")
# Handle invalid input
try:
RomanNumeral.from_string("Spam!")
except InvalidRomanNumeralError as e:
print(f"Caught expected error for 'Spam!': {e}")
try:
RomanNumeral(0)
except OutOfRangeError as e:
print(f"Caught expected error for 0: {e}")
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'roman-numerals-py'
Python module names replace hyphens with underscores, so `roman-numerals-py` must be imported as `roman_numerals_py`.
fiximport roman_numerals_py
AttributeError: module 'roman_numerals_py' has no attribute 'to_roman'
The user installed `roman-numerals-py` but is trying to use the API (e.g., `to_roman`, `from_roman`) of the `roman-numerals` library. `roman-numerals-py` uses `convert_to_roman` and `convert_from_roman`.
fixEither use the correct function names from `roman-numerals-py` (e.g., `from roman_numerals_py import convert_to_roman`), or install and use the recommended `roman-numerals` library.
ValueError: Not a valid Roman numeral
The input string provided to `convert_from_roman` does not represent a valid Roman numeral according to the library's rules (e.g., 'IIII', 'VX').
fixProvide a syntactically correct and valid Roman numeral string, such as `convert_from_roman('IV')`. ValueError: Not a valid integer to convert to Roman numerals
The integer provided to `convert_to_roman` is outside the supported range (1 to 3999), such as 0 or 4000.
fixEnsure the input integer is between 1 and 3999 (inclusive), for example, `convert_to_roman(1994)`.
Upgrade
Version history
4.1.0latest on PyPI · released Dec 17, 2025
Audit
Dependencies
roman-numeralsrequiredAs of version 4.0.0, `roman-numerals-py` is a meta-package that depends on `roman-numerals` and installs no modules itself. The core functionality is provided by `roman-numerals`.