roman-numerals

What it is and what it does

roman-numerals is a focused library for bidirectional conversion between integers and Roman numerals. It enforces the classical rules of Roman numeral formation—no character may appear more than three times consecutively—and rejects malformed input with specific exceptions. The library accepts integers from 1 to 3,999 (the range of well-formed classical numerals) and can parse both uppercase and lowercase Roman numeral strings, converting them back to their integer equivalents.

The package has no external dependencies and is designed as a lightweight utility for applications that need reliable Roman numeral handling. It supports both string representation and integer extraction, with methods for case conversion, and raises OutOfRangeError for values outside the valid range or InvalidRomanNumeralError for malformed input.

Use it for:

• Format page numbers or section headers in documents using Roman numerals.
• Parse and validate user-supplied Roman numeral input in educational or historical software.
• Convert integer values to classical Roman numeral representation for display in UI or reports.
• Validate that a string conforms to classical Roman numeral rules before processing.
• Build historical or academic applications that work with Roman numeral data.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Converts between integers and Roman numerals, supporting values from 1 to 3,999 with strict classical formatting rules and case-flexible parsing.

Yes. The package is lightweight, actively maintained, has no dependencies, supports modern Python versions, carries permissive licensing, and solves a well-defined problem with strict classical rules. Install it if you need reliable Roman numeral conversion with validation; skip it if you only need occasional formatting and can tolerate looser rules.

Install

roman-numerals on PyPI

pip install roman-numerals

uv add roman-numerals

poetry add roman-numerals

Installing roman-numerals

Before you install

Low friction: pure Python wheel with no runtime dependencies. Active maintenance as of 2025-12-17, last commit 2026-04-02, supports current Python versions (3.10–3.15).

License in practice

Dual-licensed under 0BSD or CC0-1.0 (permissive). Either license permits unrestricted use, modification, and distribution with minimal or no attribution requirements.

Quickstart

from roman_numerals import RomanNumeral

num = RomanNumeral(16)
print(str(num))  # 'XVI'

num = RomanNumeral.from_string('XVI')
print(int(num))  # 16

Requires Python 3.10 or later.

Verify before relying

• Whether the library handles mixed-case input or enforces uniform case throughout the string as described.

Package facts

Evidence: roman_numerals-4.1.0-py3-none-any.whl

Tags

More Utilities packages