Install & Compatibility
Where this runs
tested against v3.1.0 · 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.074s · 24.2MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 2.0s · import 0.058s · 25MB
25MB installed
● package 25MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
ProvDocument
✓ from prov.model import ProvDocument
✗ from prov import ProvDocument
Core classes like ProvDocument and Namespace reside in the 'prov.model' submodule.
Namespace
✓ from prov.model import Namespace
✗ from prov import Namespace
Core classes like ProvDocument and Namespace reside in the 'prov.model' submodule.
PROV_REC_NAMESPACE
✓ from prov.constants import PROV_REC_NAMESPACE
Constants are defined in the 'prov.constants' submodule.
This example demonstrates how to create a simple PROV document, define namespaces, add entities, activities, and agents, and link them with provenance relations. It then prints the PROV-N (PROV Notation) representation of the document. For JSON or XML serialization, additional dependencies and specific serializers are used.
import datetime
from prov.model import ProvDocument, Namespace, PROV_REC_NAMESPACE
# Create a new provenance document
doc = ProvDocument()
# Declare namespaces
doc.add_namespace('ex', 'http://example.org/')
doc.set_default_namespace('http://example.com/prov-example/')
# Declare entities, activities, agents
e1 = doc.entity('ex:entity1', {'prov:label': 'Example Entity 1'})
a1 = doc.activity('ex:activity1', datetime.datetime.now(), datetime.datetime.now(), {'prov:label': 'Example Activity 1'})
ag1 = doc.agent('ex:agent1', {'prov:label': 'Example Agent 1', PROV_REC_NAMESPACE['type']: PROV_REC_NAMESPACE['Person']})
# Establish relationships
doc.wasGeneratedBy(e1, a1, datetime.datetime.now())
doc.wasAssociatedWith(a1, ag1)
# Print the PROV-N representation
print(doc.get_provn())
# To serialize to PROV-JSON (requires the 'json' extra, installed with `pip install prov[json]`)
# from prov.serializers import provjson
# import json
# with open('example.json', 'w') as f:
# provjson.ProvJSONSerializer(doc).serialize(f)
Debug
Known issues
breakingPython 2.x support was removed in version 2.0.0. The library is now Python 3 only.fixUpgrade to Python 3.9+ and `prov` version 2.x. Ensure your code is compatible with Python 3.
affects: <2.0.0
breakingSupport for several End-of-Life Python versions has been dropped incrementally. Python 3.3 was removed in v1.5.3, Python 3.6 and 3.7 in v2.0.1, and Python 3.8 in v2.0.2. Current versions require Python >=3.9.fixEnsure your project runs on Python 3.9 or newer. The latest `prov` version (2.1.1) supports Python 3.9-3.13.
affects: All versions up to 2.1.1
breakingThe `rdflib` dependency, used for PROV-O (RDF) serialization, was restricted to versions less than 7 (`rdflib <7`) starting from `prov` version 2.0.1 due to compatibility issues.fixWhen installing `prov[rdf]`, ensure `rdflib` is installed as `rdflib<7` or check for newer `prov` versions that explicitly support `rdflib` 7+ if available.
affects: >=2.0.1
deprecatedThe `pydotplus` dependency for graphical output was replaced by `pydot` in version 1.5.1.fixIf you were using `pydotplus` with older `prov` versions, switch to `pydot` for graphical visualizations with newer `prov` releases. Ensure `Graphviz` is also installed.
affects: >=1.5.1
breakingThe underlying data model for PROV documents underwent a rewrite in version 1.0.0, introducing incompatibilities with pre-1.0 versions. Methods like `add_record()` were renamed to `new_record()` in v1.0.1, and references to PROV elements became `QualifiedName` instances.fixReview the changelog for `prov` version 1.0.0 and 1.0.1. Significant code changes may be required for migration from pre-1.0 versions.
affects: <1.0.0
gotchaNaming a local Python file or module `prov.py` will cause an `ImportError` due to a name collision with the `prov` library itself.fixRename your local file or module to something other than `prov.py` to avoid masking the actual library.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'prov'
The 'prov' library is not installed in your current Python environment, or there is a naming conflict with a local file named 'prov.py'.
fixEnsure the library is installed using pip: `pip install prov`. If a local file named `prov.py` exists, rename it to avoid shadowing the installed package.
AttributeError: 'ProvDocument' object has no attribute 'non_existent_method'
You are attempting to access a method or attribute on a `ProvDocument` (or another `prov.model` object) that does not exist or is misspelled. This often happens when trying to use a method that is not part of the `prov` API.
fixCheck the official 'prov' library documentation for the correct method or attribute name. For example, to serialize to PROV-N, use `document.serialize(format='provn')` instead of a custom method. Ensure correct spelling and case.
ValueError: Invalid PROV-DM identifier
This error occurs when an invalid string or format is provided where a PROV-DM identifier (e.g., for an entity, activity, or agent) is expected, often when creating `QualifiedName` objects or adding records to a `ProvDocument`. This can also be raised by `prov.model.ProvExceptionInvalidQualifiedName`.
fixEnsure that identifiers conform to the PROV-DM specification, typically being valid `QualifiedName` instances or strings that can be resolved into valid qualified names. For example, use `prov.model.QualifiedName` with a defined namespace and local name: `doc.agent(EX. 'john_doe')` where `EX` is a defined namespace.
XML Parsing Error: not well-formed
The PROV-XML document you are trying to parse is not well-formed, meaning it contains syntax errors such as missing tags, incorrect nesting, or invalid characters, which prevents the `prov` library's XML parser from processing it.
fixInspect the XML file for syntax errors, paying close attention to the line and column numbers indicated in the error message. Ensure all tags are properly closed and nested, and that no invalid characters are present. Use an XML validator tool to pinpoint exact issues.
Prefix must resolve to a namespace
This error typically occurs during PROV-XML or PROV-O serialization/deserialization when a prefix used in an identifier (e.g., 'ex:myEntity') has not been properly bound to a corresponding namespace URI in the PROV document.
fixDefine all prefixes used in your PROV document by registering them with a `prov.model.Namespace` object and adding them to your `ProvDocument`. Example: `EX = prov.model.Namespace('ex', 'http://example.org/')` and then `doc.add_namespace(EX)` or `doc.set_default_namespace('http://example.org/')`. Upgrade
Version history
3.1.0latest on PyPI · released Aug 7, 2026
Audit
Dependencies
rdfliboptionalRequired for PROV-O (RDF) serialization/deserialization. Version must be less than 7 for compatibility with prov 2.x.
pydotoptionalRequired for graphical visualization of PROV documents (generates DOT files for Graphviz).