---
id: roman-numerals
version: "4.1.0"
license: 0BSD OR CC0-1.0
license_treatment: permissive
maintenance: active
---

# roman-numerals — Manipulate well-formed Roman numerals

License: permissive · Maintenance: active · Downloads: 12.7M/mo

## 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 above — 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

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

- License: 0BSD OR CC0-1.0 (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 12.7M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

roman numeral conversion, integer to roman numeral, parse roman numerals, roman numeral library, classical roman numeral formatter, roman numeral validation, numeral-conversion, validation

[View on SkillFed](https://skillfed.io/packages/roman-numerals) · [View on PyPI](https://pypi.org/project/roman-numerals/)