hl7apy – Python HL7 v2 Library

1.3.5 verified Tue May 12 auth: no python install: verified quickstart: verified maintenance

Python library for parsing, creating, and manipulating HL7 v2.x messages. Supports HL7 versions 2.1 through 2.7, provides both high-level and low-level APIs for message construction, validation against HL7 schemas, and MLLP (Minimal Lower Layer Protocol) transport support.

pip install hl7apy

Common errors

error ModuleNotFoundError: No module named 'hl7apy' ↓

cause The `hl7apy` library is not installed in your Python environment or is not accessible via your Python path.

fix

Install the library using pip: pip install hl7apy

error hl7apy.exceptions.ParserError: Invalid message ↓

cause The input string provided to `hl7apy.parser.parse_message` does not conform to the expected HL7 v2 message format or contains invalid delimiters/characters, preventing proper parsing.

fix

Ensure the input string is a valid HL7 v2 message with correct segment delimiters (often \r or \n needs to be replaced with \r), field separators, and an MSH segment. You might need to preprocess the message string, e.g., message.replace('\n', '\r') or explicitly set find_groups=False if dealing with non-standard messages.

error hl7apy.exceptions.ChildNotFound: No child named <ELEMENT_NAME> ↓

cause You are attempting to access or add an HL7 element (segment, field, component) by a name that is not defined in the HL7 standard structure for the message type and version being used. This often happens in strict validation mode.

fix

Verify the HL7 message structure and element names against the official HL7 specification for your message type and version. If you intend to add a non-standard or 'Z' element, consider using validation_level=VALIDATION_LEVEL.TOLERANT during message creation or element assignment.

error ValueError: <VALUE> is not an HL7 valid date value ↓

cause An invalid date, time, or datetime string was assigned to a field or component that expects an HL7-compliant date/time format, and the validation level is set to strict.

fix

Ensure that date/time values adhere to HL7's specified formats (e.g., YYYYMMDD, YYYYMMDDHHMMSS, YYYYMMDDHHMMSS.sss[+/-ZZZZ]). If the format is intentionally non-standard, set the validation level to VALIDATION_LEVEL.TOLERANT for the message or element.

Warnings

gotcha HL7 messages use \r (carriage return) as the segment separator, not \n. Using \n will cause parse failures. ↓

fix Use \r between segments: 'MSH|...|2.5\rPID|...' and ensure raw strings or proper escaping.

gotcha Validation is strict by default. Setting a field to a value that doesn't match the HL7 datatype raises an exception. ↓

fix Pass validation_level=VALIDATION_LEVEL.TOLERANT when constructing or parsing: Message('ADT_A01', validation_level=VALIDATION_LEVEL.TOLERANT)

gotcha parse_message() expects the full message string including MSH segment. Passing a single segment string will raise InvalidEncodingChars or similar errors. ↓

fix Use parse_segment() from hl7apy.parser for individual segments, or always pass complete messages to parse_message().

gotcha Field/component access uses 1-based HL7 numbering (e.g., msh_9_1), but the MSH segment's field numbering starts at MSH-1 which is the field separator itself. MSH-3 is the sending application. ↓

fix Refer to HL7 spec field numbers. Access sending application as m.msh.msh_3, not m.msh.msh_2.

deprecated The library has infrequent releases. Last major update was 1.3.4. Python 2 support was dropped but some legacy patterns remain in documentation. ↓

fix Use Python 3.6+ and verify examples against current API. Check GitHub issues for compatibility notes.

gotcha to_er7() returns the ER7-encoded string but does not add trailing segment separators. Concatenating multiple to_er7() outputs requires manual \r insertion. ↓

fix Always join segments with \r when building composite output manually.

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) - - 0.01s 31.9M

3.10 slim (glibc) - - 0.01s 32M

3.11 alpine (musl) - - 0.03s 34.7M

3.11 slim (glibc) - - 0.02s 35M

3.12 alpine (musl) - - 0.02s 26.0M

3.12 slim (glibc) - - 0.02s 27M

3.13 alpine (musl) - - 0.02s 25.6M

3.13 slim (glibc) - - 0.03s 26M

3.9 alpine (musl) - - 0.01s 29.5M

3.9 slim (glibc) - - 0.01s 30M

Imports

Message
wrong
```
from hl7apy import parse_message
```
correct
```
from hl7apy.parser import parse_message
```
parse_message lives in hl7apy.parser, not the top-level package.
Message (construction)
wrong
```
from hl7apy import Message
```
correct
```
from hl7apy.core import Message
```
Message class is in hl7apy.core, not the top-level namespace.
Segment
```
from hl7apy.core import Segment
```
Segment is in hl7apy.core alongside Message, Group, Field, Component, etc.

Quickstart verified last tested: 2026-05-12

Create and parse HL7 v2.5 messages using hl7apy.

from hl7apy.core import Message
from hl7apy.parser import parse_message

# Create a new ADT^A01 message
m = Message('ADT_A01')
m.msh.msh_9.msh_9_1 = 'ADT'
m.msh.msh_9.msh_9_2 = 'A01'
m.msh.msh_10 = 'MSG00001'
m.msh.msh_11.msh_11_1 = 'P'
m.msh.msh_12 = '2.5'
print(m.to_er7())

# Parse an existing HL7 message
raw = 'MSH|^~\\&|SENDING|FACILITY|RECEIVING|FACILITY|20230101120000||ADT^A01|MSG00001|P|2.5\rPID|||12345||Doe^John'
parsed = parse_message(raw)
print(parsed.pid.pid_5.pid_5_1.value)