Install & Compatibility
Where this runs
tested against v2.3.3 · 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.000s · 27.4MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 1.7s · import 0.000s · 28MB
26MB installed
● package 26MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
X12Message
✓ from pyx12.x12message import X12Message
X12N
✓ from pyx12.map_walker import X12N
X12N is used for walking and validating HIPAA transaction sets.
This quickstart demonstrates how to parse an X12 EDI file using `X12Message` and iterate through its segments. It also shows the basic setup for `X12N` for validation, though full validation requires proper configuration of X12 map files (schemas) which are not included in the basic installation.
import os
from pyx12.x12message import X12Message
from pyx12.map_walker import X12N
# Create a dummy X12 file for demonstration
edi_data = """ISA*00* *00* *ZZ*SENDERID *ZZ*RECEIVERID *200101*1200*U*00401*000000001*0*T*:~GS*HI*SENDER*RECEIVER*20010101*1200*1*X*004010VICS~ST*837*0001*005010X222~BHT*0019*00*01*20010101*1200*CH~HL*1**20*1~PRV*BI*PXC*01~NM1*85*1*SMITH*JOHN*P***XX*1234567890~PER*IC*JOHN SMITH*TE*5555551212~SE*10*0001~GE*1*1~IEA*1*000000001~"""
# Save the EDI data to a temporary file
file_path = "test_837.edi"
with open(file_path, "w") as f:
f.write(edi_data)
# Initialize X12Message with the file
try:
# Using a dummy map_path for basic parsing, real validation requires actual maps
# For a full validation, set X12_MAP_PATH_INI or pass map_path parameter
# Example: map_path = os.environ.get('X12_MAP_PATH', './maps')
msg = X12Message(file_path)
# Iterate through segments
print("\n--- Segments --- ")
for segment in msg.walk_segments():
print(f"Segment: {segment.get_tag()}, Elements: {segment.get_elements()}")
# Perform basic validation (requires map files to be configured or provided)
print("\n--- Validation (requires map files) ---")
# Note: For this quickstart, actual validation will likely fail without proper map setup.
# Configure map paths via environment variable or 'map_path' parameter in X12N.
# os.environ['X12_MAP_PATH'] = 'path/to/your/map/files'
walker = X12N(msg)
# validation_result = walker.validate()
# print(f"Validation Result: {validation_result.get_state()}")
print("Note: Full validation requires X12 map files. See documentation for setup.")
except Exception as e:
print(f"An error occurred: {e}")
finally:
# Clean up the dummy file
if os.path.exists(file_path):
os.remove(file_path)
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'pyx12'
The `pyx12` package is not installed in your current Python environment.
fixRun `pip install pyx12` to install the library.
pyx12.errors.X12MapNotFoundException: Can not find map file for ...
The library could not locate the necessary X12 map (schema) file for the transaction set and version being processed, or the configured `X12_MAP_PATH` is incorrect.
fixEnsure X12 map files are available and their directory is correctly specified via the `X12_MAP_PATH` environment variable or the `map_path` parameter when initializing `X12Message` or `X12N`.
SyntaxError: invalid syntax (on line ...)
You are attempting to run PyX12 v3.x (Python 3 only) code in a Python 2.x environment, or vice-versa with v2.x on Python 3 (less common).
fixIf using PyX12 v3.x, ensure you are running Python 3.6+. If you require Python 2.x compatibility, you must use PyX12 v2.x and its corresponding syntax.
Upgrade
Version history
4.0.0latest on PyPI · released May 5, 2026
Audit
Dependencies
lxmloptionalRequired for XML output features (e.g., converting X12 to XML).
python-xattroptionalUsed on Linux for file extended attributes, optional for core functionality.
Resources
No resource links recorded.