Install & Compatibility
Where this runs
tested against v1.4.1 · 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 1.004s · 20.5MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 2.8s · import 0.984s · 21MB
18MB installed
● package 18MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
OpenDocumentText
✓ from odf.opendocument import OpenDocumentText
Used for creating new ODT documents.
load
✓ from odf.opendocument import load
Used for loading existing ODF documents.
P
✓ from odf.text import P
Used for creating paragraphs.
Style
✓ from odf.style import Style
Used for defining custom styles.
teletype
✓ from odf import teletype
Module for handling text insertion with proper whitespace handling.
This quickstart demonstrates how to create a simple OpenDocument Text (.odt) file, add a paragraph with text, and save the document using ODFPy. This is a common starting point for generating new ODF files.
from odf.opendocument import OpenDocumentText
from odf.text import P
import os
# Create a new ODT document
textdoc = OpenDocumentText()
# Create a paragraph and add some text
p = P(text="Hello, ODFPy World!")
# Add the paragraph to the document's text body
textdoc.text.addElement(p)
# Save the document to 'helloworld.odt'
# The 'prettyprint=True' argument formats the XML for readability.
try:
output_filename = os.path.join(os.getcwd(), "helloworld.odt")
textdoc.save(output_filename, prettyprint=True)
print(f"Document '{output_filename}' created successfully.")
except Exception as e:
print(f"Error saving document: {e}")
Debug
Known issues
gotchaThe official documentation for ODFPy is often described as highly technical and lacking in conceptual examples, making it challenging for newcomers. Users frequently resort to studying the provided examples and source code to understand usage patterns.fixRefer to the examples provided in the GitHub repository (https://github.com/eea/odfpy/tree/master/examples) and consider blog posts or third-party tutorials for practical usage. Examining the generated XML of simple documents can also aid understanding.
affects: All versions
gotchaWhile officially considered 'active maintenance', ODFPy has an infrequent release cycle (latest release 1.4.1 in January 2020). For projects requiring more frequent updates or active development, alternatives like `odfdo` (also listed by The Document Foundation) might be considered.fixEvaluate project needs against the library's release cadence. If cutting-edge features or rapid bug fixes are critical, investigate `odfdo` or other ODF manipulation libraries.
affects: 1.4.1 and potentially prior versions
gotchaODFPy rigorously enforces OpenDocument Specification 1.2 through grammar checks. This means attempts to add invalid elements, unknown attributes, or text to unsupported elements will raise exceptions, preventing the creation of malformed documents. This strictness can be a 'gotcha' for users expecting more lenient XML handling.fixFamiliarize yourself with the OpenDocument Specification structure or create minimal ODF documents manually in LibreOffice/OpenOffice and inspect their XML content to understand valid structures when encountering validation errors. The error messages usually provide clues about the specific ODF rule violated.
affects: All versions
gotchaMany examples and the library's design are more geared towards *creating* new ODF documents rather than *reading* and parsing content from existing ones. Finding clear, simple examples for extracting data from existing .odt or .ods files can be challenging.fixFor reading existing ODF files, be prepared to explore the document's XML structure (e.g., `doc.getElementsByType(P)`) and iterate through elements. Community-contributed examples (like the `read-ods-with-odfpy` project on GitHub) might offer more insights into reading patterns.
affects: All versions
deprecatedOlder documentation and examples might point to the `joinup.ec.europa.eu` domain. This source is obsolete and should not be used for current information or downloads.fixAlways refer to the official GitHub repository (https://github.com/eea/odfpy) and PyPI page (https://pypi.org/project/odfpy/) for the most up-to-date information, documentation, and examples.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'odfpy'
The 'odfpy' package is not installed in the current Python environment or the Python interpreter being used does not have access to the installed package.
fixInstall the package using pip: `pip install odfpy`
ModuleNotFoundError: No module named 'odf'
Users often mistakenly try to import 'odf' directly instead of 'odfpy', or this error appears when 'odfpy' is a dependency of another library (like pandas) and the import path is incorrect or the dependency is missing.
fixEnsure you are importing `odfpy` correctly, usually `import odfpy` or `from odfpy import ...`. If it's a dependency, ensure `odfpy` is installed: `pip install odfpy`.
AttributeError: Text instance has no attribute encode
This error typically occurs when trying to call the `encode()` method on an `odfpy` `Text` object, which does not possess this method, often due to incorrect string handling, especially in mixed Python 2/3 codebases or when dealing with unicode characters.
fixEnsure you are working with Python 3 strings (unicode by default) and convert explicitly to bytes if encoding is needed, for example, `str(text_instance).encode('utf-8')` if `text_instance` truly contains the text you wish to encode. ERROR: Could not find a version that satisfies the requirement setuptools>=40.8.0
This installation error occurs when `pip` tries to build `odfpy` from source and cannot find a compatible version of `setuptools` in the isolated build environment, particularly prevalent with Python 3.12+ where `setuptools` is no longer pre-installed in virtual environments.
fixTry installing `odfpy` by disabling build isolation: `pip install --no-build-isolation odfpy`. Alternatively, ensure `setuptools` is explicitly installed in your environment before attempting `odfpy` installation: `pip install setuptools wheel`.
Upgrade
Version history
1.4.1latest on PyPI · released Jan 18, 2020
Audit
Dependencies
No dependency data recorded yet.