{"id":134,"library":"hl7","title":"python-hl7 – HL7 v2.x Message Parser","description":"A simple Python library for parsing HL7 v2.x messages. Provides segment, field, and component-level access to HL7 messages, along with MLLP (Minimal Lower Layer Protocol) client support. Does not handle HL7 FHIR (v4); it is strictly for the pipe-delimited v2.x wire format.","status":"active","version":"0.4.5","language":"python","source_language":"en","source_url":"https://github.com/johnpaulett/python-hl7","tags":["hl7","healthcare","parser","mllp","hl7v2","medical","interoperability","python"],"install":[{"cmd":"pip install hl7","lang":"bash","label":"Python"},{"cmd":"pip install hl7[mllp]","lang":"bash","label":"Python (with MLLP async client/server)"}],"dependencies":[{"reason":"Required for the async MLLP server/client functionality.","package":"aiorun","optional":true}],"imports":[{"note":"There is no HL7Message class. Use the hl7.parse() function which returns a Message object.","wrong":"from hl7 import HL7Message","symbol":"hl7.parse","correct":"import hl7\nmessage = hl7.parse(raw_message_string)"},{"note":"In 0.4.x the async MLLP client uses open_hl7_connection(). The old synchronous MLLPClient was removed.","wrong":"from hl7 import MLLPClient","symbol":"MLLPClient","correct":"from hl7.mllp import open_hl7_connection"}],"quickstart":{"code":"import hl7\n\nraw = 'MSH|^~\\\\&|SND|SND_FAC|RCV|RCV_FAC|20230101120000||ADT^A01|MSG00001|P|2.3\\rPID|||12345^^^MRG||DOE^JOHN||19800101|M\\r'\nmessage = hl7.parse(raw)\n\n# Access fields using segment(field) notation\nprint(message.segment('MSH'))       # Full MSH segment\nprint(message['MSH.9'])              # Message type: ADT^A01\nprint(message['PID.5'])              # Patient name: DOE^JOHN\nprint(message.segment('PID')[5])     # Same: DOE^JOHN","lang":"python","description":"Parse an HL7 v2.x message and access segments and fields."},"warnings":[{"fix":"Ensure raw messages use \\r: raw = raw.replace('\\n', '\\r') before parsing.","message":"HL7 v2.x messages use \\r (carriage return) as the segment separator, NOT \\n. Messages with \\n line endings will not parse correctly.","severity":"gotcha","affected_versions":"all"},{"fix":"Migrate to async: reader, writer = await open_hl7_connection(host, port). The async MLLP functionality is now part of the base `hl7` package and does not require the `[mllp]` extra.","message":"The 'mllp' installation extra was removed along with the synchronous MLLPClient class in 0.4.0. MLLP functionality is now async-only and does not require a separate 'mllp' extra. Attempting to install `hl7[mllp]` on versions >= 0.4.0 will result in a warning.","severity":"breaking","affected_versions":">= 0.4.0"},{"fix":"Use the fhir.resources package for FHIR R4/R5 resources.","message":"This library only handles HL7 v2.x pipe-delimited messages. It does NOT support HL7 FHIR (v4 JSON/XML). Use fhir.resources or fhirclient for FHIR.","severity":"gotcha","affected_versions":"all"},{"fix":"Use the string accessor message['MSH.9'] for clarity, or remember segment()[n] is 0-indexed.","message":"Field indexing is 0-based on the segment object but MSH segment counts the field separator as MSH.1, so MSH[1] returns '|' and MSH[9] returns the message type. This 1-off confusion is common.","severity":"gotcha","affected_versions":"all"},{"fix":"Check segments first: if message.segments('ZZZ'): ... or wrap in try/except KeyError.","message":"Accessing a non-existent segment with message.segment('ZZZ') raises KeyError, not returning None.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-05-12T08:13:41.553Z","next_check":"2026-06-17T00:00:00.000Z","problems":[{"fix":"Ensure the HL7 message uses carriage returns (`\\r`) as segment delimiters. If the input string uses newlines (`\\n`), replace them with `\\r` before parsing.\n\n```python\nhl7_raw_string = \"MSH|^~\\\\&|...\\nPID|...\\nOBX|...\"\nhl7_message = hl7_raw_string.replace('\\n', '\\r')\nparsed_message = hl7.parse(hl7_message)\n# Now you can access segments correctly, e.g., parsed_message['PID']\n```","cause":"The HL7 message was not correctly parsed, often due to incorrect segment termination characters (e.g., `\\n` instead of `\\r`), causing the library to only recognize the first segment or an empty message.","error":"IndexError: list index out of range"},{"fix":"Import `MLLPClient` specifically from `hl7.client` or reference it as `hl7.client.MLLPClient`.\n\n```python\nfrom hl7.client import MLLPClient\n\nhost = '127.0.0.1'\nport = 4106\n\nwith MLLPClient(host, port) as client:\n    client.send_message('test1')\n\n# Alternatively, without explicit import:\n# with hl7.client.MLLPClient(host, port) as client:\n#     client.send_message('test1')\n```","cause":"The `MLLPClient` class is part of the `hl7.client` submodule and is not directly available in the top-level `hl7` module without explicit import.","error":"NameError: name 'MLLPClient' is not defined"},{"fix":"Access segments using integer indices (e.g., `message[0]` for the first segment) or by segment name as a string key (e.g., `message['MSH']`).\n\n```python\nimport hl7\n\nhl7_message_string = \"MSH|^~\\\\&|APP|FAC|APP2|FAC2|202301010800||ADT^A01|MSG123|P|2.5\\rPID|1||12345^6^7^^MR^MDC|...\\r\"\nmessage = hl7.parse(hl7_message_string)\n\n# Correct way to access the MSH segment\nmsh_segment = message['MSH']\nprint(msh_segment)\n\n# Accessing by index (MSH is typically the first segment)\npids_segment = message # Assuming PID is the second segment\nprint(pids_segment)\n\n# Accessing a specific field in a segment (e.g., PID.3)\npatient_id = message['PID']\nprint(patient_id)\n```","cause":"The `hl7.Message` object (from the `python-hl7` library) uses list-like or dictionary-like access for its segments and fields, not direct attribute access like `message.MSH`.","error":"AttributeError: 'Message' object has no attribute 'MSH' (or any other segment name)"}],"ecosystem":"pypi","meta_description":null,"install_score":100,"install_tag":"verified","quickstart_score":80,"quickstart_tag":"verified","pypi_latest":null,"install_checks":{"last_tested":"2026-05-12","tag":"verified","tag_description":"installs cleanly on critical runtimes, fast import, recently tested","results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.02,"mem_mb":1.3,"disk_size":"18.0M"},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"mllp","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.02,"mem_mb":1.3,"disk_size":"18.0M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.01,"mem_mb":1.3,"disk_size":"18M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"mllp","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.01,"mem_mb":1.3,"disk_size":"18M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.05,"mem_mb":1.5,"disk_size":"19.9M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"mllp","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.04,"mem_mb":1.5,"disk_size":"19.9M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.04,"mem_mb":1.5,"disk_size":"20M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"mllp","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.04,"mem_mb":1.5,"disk_size":"20M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.03,"mem_mb":1.1,"disk_size":"11.7M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"mllp","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.03,"mem_mb":1.1,"disk_size":"11.7M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.03,"mem_mb":1.1,"disk_size":"12M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"mllp","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.03,"mem_mb":1.1,"disk_size":"12M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.03,"mem_mb":1.4,"disk_size":"11.4M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"mllp","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.03,"mem_mb":1.4,"disk_size":"11.4M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.03,"mem_mb":1.2,"disk_size":"12M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"mllp","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.03,"mem_mb":1.2,"disk_size":"12M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.02,"mem_mb":1.3,"disk_size":"17.5M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"mllp","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.02,"mem_mb":1.3,"disk_size":"17.5M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.02,"mem_mb":1.3,"disk_size":"18M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"mllp","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.02,"mem_mb":1.3,"disk_size":"18M"}]},"quickstart_checks":{"last_tested":"2026-05-12","tag":"verified","tag_description":"quickstart runs on critical runtimes, recently tested","results":[{"runtime":"python:3.10-alpine","exit_code":0},{"runtime":"python:3.10-slim","exit_code":0},{"runtime":"python:3.11-alpine","exit_code":0},{"runtime":"python:3.11-slim","exit_code":0},{"runtime":"python:3.12-alpine","exit_code":0},{"runtime":"python:3.12-slim","exit_code":0},{"runtime":"python:3.13-alpine","exit_code":0},{"runtime":"python:3.13-slim","exit_code":0},{"runtime":"python:3.9-alpine","exit_code":0},{"runtime":"python:3.9-slim","exit_code":0}]}}