Install & Compatibility
Where this runs
tested against v0.9.5 · 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.920 runs
installs and imports cleanly · install 0.0s · import 0.057s · 47.9MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 4.9s · import 0.052s · 48MB
47MB installed
● package 47MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Rtf_Parser
✓ from rtfparse.parser import Rtf_Parser
De_encapsulate_HTML
✓ from rtfparse.renderers.de_encapsulate_html import De_encapsulate_HTML
This quickstart demonstrates how to programmatically parse an RTF string (written to a temporary file for demonstration) and then use the `De_encapsulate_HTML` renderer to extract any embedded HTML content, saving it to another temporary file. The extracted HTML is then printed to the console.
import pathlib
from rtfparse.parser import Rtf_Parser
from rtfparse.renderers.de_encapsulate_html import De_encapsulate_HTML
import os
import tempfile
# Create a dummy RTF file for demonstration
# In a real scenario, you would read an existing RTF file.
rtf_content = r"{\rtf1\ansi\deff0 This is some {\b bold} text and a line break.\par This is a new line.}"
temp_rtf_file = pathlib.Path(tempfile.gettempdir()) / "dummy_example.rtf"
temp_html_file = pathlib.Path(tempfile.gettempdir()) / "extracted_example.html"
try:
# Write dummy RTF content to a temporary file
with open(temp_rtf_file, "w", encoding="ascii") as f:
f.write(rtf_content)
print(f"Created temporary RTF file: {temp_rtf_file}")
# Programmatic usage: Parse the RTF file
parser = Rtf_Parser(rtf_path=temp_rtf_file)
parsed_document = parser.parse_file()
# Render the parsed RTF to extract HTML content
renderer = De_encapsulate_HTML()
with open(temp_html_file, mode="w", encoding="utf-8") as html_file:
renderer.render(parsed_document, html_file)
print(f"RTF parsed and HTML extracted to: {temp_html_file}")
# Display the extracted HTML content
with open(temp_html_file, "r", encoding="utf-8") as f:
print("\nExtracted HTML content:")
print(f.read())
except Exception as e:
print(f"An error occurred: {e}")
finally:
# Clean up temporary files
if temp_rtf_file.exists():
os.remove(temp_rtf_file)
print(f"Cleaned up {temp_rtf_file}")
if temp_html_file.exists():
os.remove(temp_html_file)
print(f"Cleaned up {temp_html_file}")
Debug
Known issues
gotchaThe first execution of the `rtfparse` executable (CLI) will trigger a configuration wizard. This wizard creates a `.rtfparse` folder in the user's home directory to store configuration files and logs. This automatic setup might be unexpected for some users.fixUsers can press 'A' for automatic configuration during the first run or manually configure settings if preferred. For programmatic use, this initial setup does not directly interfere with script execution, but logs might still be generated.
affects: All versions
gotchaThe `HTML_Decapsulator` primarily extracts raw HTML embedded within the RTF structure. It does not fully re-apply RTF-specific styles (like bolding, font size, or specific fonts) during the conversion to plain HTML. This can result in a loss of some visual formatting in the output HTML compared to the original RTF document's appearance.fixFor precise styling, manual CSS application or a more advanced RTF-to-HTML conversion library capable of interpreting and translating RTF formatting directives might be necessary. This library is focused on 'decapsulating' existing HTML rather than a full RTF rendering to HTML.
affects: All versions up to 0.9.5
gotchaThe `--embed-img` option for the `rtfparse` command-line interface, intended for embedding images into decapsulated HTML, is currently non-functional in all 0.x.x versions. This feature is planned for implementation in `rtfparse` version 1.x.fixUsers needing to embed images should await the 1.x release or implement custom logic to handle image embedding after HTML extraction.
affects: All 0.x.x versions up to 0.9.5
gotchaWhen providing file paths to `Rtf_Parser`, incorrect or non-existent paths will lead to a `FileNotFoundError`. This is a common pitfall, especially when dealing with dynamic paths or different operating system conventions.fixAlways ensure that the `rtf_path` provided to `Rtf_Parser` is a valid and accessible `pathlib.Path` object pointing to an existing RTF file. Use `pathlib.Path.exists()` for verification or implement robust error handling.
affects: All versions
gotchaRTF documents can contain complex elements (e.g., text boxes, columns, embedded images, headers/footers, nested tables) that are challenging to convert accurately to HTML. When parsing such complex RTF files, the resulting HTML might suffer from significant formatting errors, elements disappearing, or layout issues due to the inherent 'sensitivity' of RTF-to-HTML conversion.fixSimplify RTF documents where possible, especially if the primary goal is HTML conversion. Be aware that precise replication of all RTF formatting in HTML is often difficult across different parsing and rendering engines.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'rtfparse'
The rtfparse library has not been installed in the current Python environment.
ImportError: cannot import name 'HTML_Decapsulator' from 'rtfparse'
The HTML_Decapsulator class is located in the rtfparse.decapsulator submodule, not directly in the top-level rtfparse package.
fixfrom rtfparse.decapsulator import HTML_Decapsulator
AttributeError: 'str' object has no attribute 'read'
RTFParser.read_file() expects a file-like object (e.g., from open()) but received a string representing the file path instead.
fixwith open('document.rtf', 'rb') as f: rtf_parser = RTFParser.read_file(f) rtfparse.errors.RTFParseError
The provided RTF document is malformed, corrupted, or contains structures that the parser cannot interpret correctly.
fixEnsure the RTF input is valid and well-formed, or try parsing a different RTF file to diagnose if the issue is with the specific document.
Upgrade
Version history
0.9.5latest on PyPI · released Jul 8, 2025
Audit
Dependencies
extract-msgoptionalRequired for CLI usage to process MS Outlook message files (.msg) that contain RTF content.
compressed_rtfoptionalRequired for CLI usage to decompress RTF content from MS Outlook message files.
argcompleteoptionalProvides command-line argument completion for the rtfparse executable.