Install & Compatibility
Where this runs
tested against v5.2 · 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.95 runs
installs and imports cleanly · install 0.0s · import 0.010s · 17.8MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.5s · import 0.006s · 18MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
toRoman
✓ import roman
roman.toRoman(...)
fromRoman
✓ import roman
roman.fromRoman(...)
InvalidRomanNumeralError
✓ from roman import InvalidRomanNumeralError
✗ import roman.InvalidRomanNumeralError
Exceptions are typically imported directly from the module or accessed as attributes of the imported module.
This quickstart demonstrates how to convert between integers and Roman numerals using `roman.toRoman()` and `roman.fromRoman()`. It also shows how the library handles the special case for zero ('N') and catches errors for invalid Roman numeral input.
import roman
# Convert integer to Roman numeral
numeral = roman.toRoman(1994)
print(f"1994 in Roman numerals: {numeral}")
# Convert Roman numeral to integer
integer = roman.fromRoman('MCMXCIV')
print(f"MCMXCIV as an integer: {integer}")
# Example with zero (N)
zero_numeral = roman.toRoman(0)
print(f"0 in Roman numerals: {zero_numeral}")
# Handling invalid input
try:
invalid_int = roman.fromRoman('ABC')
print(invalid_int)
except roman.InvalidRomanNumeralError as e:
print(f"Error converting 'ABC': {e}")
Debug
Known issues
breakingThe `roman` library frequently drops support for older Python versions. For example, version 5.2 dropped support for Python 3.9, and version 5.0 removed support for Python 3.7 and 3.8. Always check the `requires_python` metadata or changelog before upgrading to ensure compatibility with your environment.fixConsult the `roman` library's PyPI page or GitHub changelog for `requires_python` information. Upgrade your Python interpreter if necessary, or pin to an older `roman` version.
affects: 5.0, 5.2 and later major/minor releases
gotchaProviding malformed or non-Roman numeral strings to `roman.fromRoman()` will raise an `InvalidRomanNumeralError`. This is intended behavior, but users should be aware of this specific exception for robust error handling.fixImplement `try-except roman.InvalidRomanNumeralError` blocks when parsing user input or external data that might contain invalid Roman numerals.
affects: All versions
deprecatedThe behavior related to the 'N' representation for zero has changed. As of version 5.1, 'undocumented special behavior for N' was hidden behind a method parameter. This implies that direct or implicit handling of 'N' might require explicit parameter usage or could behave differently in future versions.fixIf relying on the 'N' representation for zero, consult the official GitHub repository's source code or documentation (if available) to understand the current explicit method parameter required for its use.
affects: 5.1 and later
gotchaWhile the `roman` library handles zero, standard Roman numeral systems typically represent integers between 1 and 3999 (or higher with specific conventions). Attempting to convert numbers significantly outside this range, especially very large numbers or negative numbers (other than 0, which is 'N'), might not produce conventionally recognized Roman numerals or could lead to unexpected behavior if not explicitly handled by the library. The library's `toRoman` function will raise `roman.InvalidRomanNumeralError` for negative numbers or numbers above 3999. fixValidate input integers to `roman.toRoman()` to be within the conventionally supported range (typically 0-3999) if strict classical Roman numeral representation is desired, or handle `roman.InvalidRomanNumeralError` for out-of-range inputs.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'roman'
The 'roman' library has not been installed in your Python environment.
ValueError: Parameter must be between 1 and 3999 inclusive.
The integer provided to `roman.to_roman()` is outside the valid range for standard Roman numerals (1 to 3999).
fixEnsure the number is within the range [1, 3999], e.g., `roman.to_roman(1994)`.
ValueError: Parameter must be a valid Roman numeral string.
The string provided to `roman.from_roman()` does not represent a valid Roman numeral.
fixProvide a well-formed Roman numeral string, e.g., `roman.from_roman('MCMXCIV')`. TypeError: Parameter must be an integer.
The input provided to `roman.to_roman()` is not an integer.
fixPass an integer value to `roman.to_roman()`, e.g., `roman.to_roman(42)`.
AttributeError: module 'roman' has no attribute 'toRoman'
The function to convert Arabic numerals to Roman numerals is `roman.to()`, not `roman.toRoman()`.
fiximport roman
print(roman.to(1994))
Upgrade
Version history
5.2latest on PyPI · released Nov 11, 2025
Audit
Dependencies
No dependency data recorded yet.