Install & Compatibility
Where this runs
tested against v26.7.19.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
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
ResolvingParser
✓ from prance import ResolvingParser
The primary parser for specs with resolved references.
BaseParser
✓ from prance import BaseParser
For parsing specs without resolving references.
This quickstart demonstrates how to use `ResolvingParser` to load an OpenAPI/Swagger specification from a file (or URL) and access its fully resolved dictionary representation.
from prance import ResolvingParser
import os
# Example OpenAPI/Swagger spec content (YAML format for demonstration)
# In a real scenario, this would be loaded from a file or URL
spec_content = """
openapi: 3.0.0
info:
title: Sample API
version: 1.0.0
paths:
/items:
get:
summary: Get all items
responses:
'200':
description: A list of items
"""
# Create a dummy spec file for the example
with open('sample_spec.yaml', 'w') as f:
f.write(spec_content)
try:
# Initialize the parser with the path to your spec file
parser = ResolvingParser('sample_spec.yaml')
# The fully resolved specification is available as a dictionary
resolved_spec = parser.specification
print(f"API Title: {resolved_spec['info']['title']}")
print(f"API Version: {resolved_spec['info']['version']}")
print("Specification parsed successfully.")
# Example with a URL (requires internet access)
# parser = ResolvingParser('http://petstore.swagger.io/v2/swagger.json')
# resolved_spec = parser.specification
# print(f"Petstore API Title: {resolved_spec['info']['title']}")
finally:
# Clean up the dummy spec file
if os.path.exists('sample_spec.yaml'):
os.remove('sample_spec.yaml')
prance --version
Debug
Known issues
breakingPrance version 25.04.08.0 dropped support for Python 3.8 and 3.9. It now supports Python 3.11, 3.12, and 3.14. Earlier, Python 2.7 and 3.4 support was removed in versions prior to 0.17.0.fixUpgrade Python environment to a supported version (e.g., 3.10 or newer, preferably 3.11+ for latest Prance).
affects: 25.04.08.0 and later for 3.8/3.9 removal; 0.17.0 and later for 2.7/3.4 removal
breakingVersion 25.04.08.0 migrated its underlying JSON reference resolution engine from `jsonschema` to `referencing`. While the public API is generally stable, advanced users directly interacting with resolver internals might experience breaking changes.fixReview code that directly manipulates internal resolver components. Test thoroughly after upgrading.
affects: 25.04.08.0 and later
gotchaPrance's validation backends (`openapi-spec-validator`, `swagger-spec-validator`, `flex`) are optional dependencies. For full functionality and recommended usage, install with extras like `pip install prance[osv,icu,cli]`. If no backend is installed, validation might be limited or fail.fixInstall Prance with the appropriate extra dependencies for your desired validation backend (e.g., `prance[osv]` for OpenAPI 3.0+ validation) and other features (e.g. `[icu]` for better Unicode handling, `[cli]` for command line tools).
affects: All versions
deprecatedVersion 25.04.08.0 switched the preferred YAML mimetype from `x-yaml` to the official `yaml` form. While older forms might still be handled, it's best to use the official mimetype.fixEnsure any custom handling or generation of OpenAPI/Swagger specs uses the official `yaml` mimetype.
affects: 25.04.08.0 and later
gotchaAs of version 0.8, Prance defaults to `flex` as the validation backend if available. Note that `flex` accepts integer status codes despite them not being valid JSON, which might lead to less strict validation than other backends. You can explicitly specify a backend in the parser constructor (e.g., `ResolvingParser(..., backend='openapi-spec-validator')`).fixIf strict JSON validation for HTTP status codes is required, explicitly set `backend='openapi-spec-validator'` or `backend='swagger-spec-validator'` during parser initialization, and ensure that backend is installed.
affects: 0.8 and later
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'prance'
The 'prance' library is not installed in the Python environment being used, or the environment is not correctly activated/configured.
fixInstall the library using pip: `pip install prance`
prance.ValidationError: Could not parse specifications!
The provided OpenAPI/Swagger specification file is invalid, malformed, or contains errors that prevent 'prance' from parsing or validating it. This can also be caused by the validation backend (e.g., openapi-spec-validator) raising an error.
fixEnsure the OpenAPI/Swagger specification file is valid YAML or JSON, and check it against an online validator. Examine the full traceback for more specific details from the underlying validation backend.
prance.util.url.ResolutionError: Unresolvable JSON pointer: '...'
'prance' could not resolve a '$ref' reference within the OpenAPI/Swagger specification. This often happens if the referenced file or path within the file does not exist or is inaccessible.
fixVerify that all '$ref' pointers correctly point to existing files or valid paths within the specification. Ensure relative paths are correct and that 'prance' has access to referenced files.
AttributeError: 'dict' object has no attribute 'decode'
This typically occurs when 'prance' tries to perform a string decoding operation on an object that is already a dictionary, suggesting an issue with the input spec or how it's being processed by the CLI or an internal function expecting a byte string.
fixThis specific error was reported in an old GitHub issue and might be resolved in newer versions. If encountered, ensure the input specification is valid and try updating the 'prance' library to the latest version (`pip install --upgrade prance`). If using the CLI, ensure the file is correctly formatted (YAML/JSON) and accessible.
Upgrade
Version history
26.7.19.0latest on PyPI · released Jul 19, 2026
Audit
Dependencies
openapi-spec-validatoroptionalOne of the validation backends, recommended with `[osv]` extra.
swagger-spec-validatoroptionalAn older validation backend, available with `[ssv]` extra.
flexoptionalA validation backend.
PyICUoptionalFor improved Unicode handling, available with `[icu]` extra. Requires system-level 'libicu-dev' or 'libicu-devel' installation.
clickoptionalRequired for Command Line Interface (CLI) functionality, available with `[cli]` extra.
referencingrequiredUsed for JSON reference resolution since version 25.04.08.0.