FHIR Resources (Python)

8.0.0 verified Tue May 12 auth: no python install: verified quickstart: verified

Python library for FHIR (Fast Healthcare Interoperability Resources) providing Pydantic-based models for all FHIR resource types. Supports FHIR R4, R4B, R5, STU3, and DSTU2. Built on Pydantic v2 for validation, serialization, and deserialization of FHIR JSON. Current version targets FHIR R5 by default with backwards-compatible imports for older FHIR versions.

pip install fhir.resources

Common errors

error ModuleNotFoundError: No module named 'pydantic_core._pydantic_core' ↓

cause This error typically occurs when `fhir.resources` (version 7.0.0 or higher) is installed in an environment where Pydantic v1 is present, or an older version of `fhir.resources` (prior to 7.0.0) is attempting to run with Pydantic v2. `fhir.resources` 7.x+ depends on Pydantic v2, which includes `pydantic_core`.

fix

Ensure that your Pydantic installation is compatible with your fhir.resources version. For fhir.resources v7.0.0 and above, upgrade Pydantic to version 2.x: pip install --upgrade pydantic. For older fhir.resources versions, you might need to downgrade Pydantic: pip install 'pydantic<2'.

error pydantic.error_wrappers.ValidationError: 1 validation error for Patient\nresource -> status\n field required (type=value_error.missing) ↓

cause This Pydantic validation error indicates that a required field within the FHIR resource (e.g., `status` for a `Patient` resource) is missing in the data provided when instantiating the `fhir.resources` model, violating the FHIR specification.

fix

Provide a valid value for the missing required field. For example, when creating a Patient resource, ensure all mandatory fields as per the FHIR specification are included:

from fhir.resources.R5.patient import Patient

patient_data = {
    "resourceType": "Patient",
    "id": "example",
    "active": True,
    "name": [
        {
            "use": "official",
            "family": "Chalmers",
            "given": ["Peter"]
        }
    ],
    "gender": "male",
    "birthDate": "1974-12-25"
}

patient = Patient(**patient_data)
# Or, if loading from JSON string
# patient = Patient.parse_raw(json_string_data)

Note: Patient itself does not have a 'status' field, but other resources like Observation or ServiceRequest do. The example Patient data is shown to illustrate providing required fields.

error AttributeError: module 'fhir.resources' has no attribute 'R4' ↓

cause This error occurs when trying to import FHIR resources from a specific version (like R4) using an incorrect path. The `fhir.resources` library (version 7.0.0+) defaults to R5, and older versions (STU3, R4B) are located in specific sub-packages. R4 is explicitly noted to not have its own sub-package in newer versions, with R4B being the closest available.

fix

Import resources from the correct FHIR version sub-package. For R4B resources, use from fhir.resources.R4B.patient import Patient. For STU3 resources, use from fhir.resources.STU3.patient import Patient. If you intend to use the default R5, simply use from fhir.resources.R5.patient import Patient or from fhir.resources.patient import Patient (as R5 is the default).

error pydantic.error_wrappers.ValidationError: ... extra fields not permitted (type=value_error.extra) ↓

cause This validation error from Pydantic indicates that the input JSON or dictionary for a FHIR resource contains fields that are not defined in the FHIR specification for that resource type or its current profile, or it may contain elements from a different FHIR version.

fix

Ensure that the input data strictly conforms to the FHIR specification for the target resource and version. Remove any extraneous fields that are not part of the standard, or ensure that you are using the correct FHIR version's resource definition. For example, if parsing a resource, inspect the input JSON to remove unexpected keys:

from fhir.resources.R5.patient import Patient

# This will raise 'extra fields not permitted' because 'unexpectedField' is not part of Patient
malformed_data = {
    "resourceType": "Patient",
    "id": "example",
    "active": True,
    "gender": "male",
    "unexpectedField": "some value"
}

try:
    patient = Patient(**malformed_data)
except Exception as e:
    print(e)

# Corrected data
correct_data = {
    "resourceType": "Patient",
    "id": "example",
    "active": True,
    "gender": "male"
}
patient = Patient(**correct_data)

Warnings

breaking fhir.resources 7.x+ requires Pydantic v2. Pydantic v2 leverages modern Python typing features (like the '|' operator for unions) that are fully supported from Python 3.10 onwards. Running fhir.resources 7.x+ with Python 3.9 or older (alongside Pydantic v2) will result in a TypeError due to unrecognized syntax. Projects still on Pydantic v1 must use fhir.resources 6.x. ↓

fix Either upgrade your Python environment to 3.10 or later and install 'pydantic>=2.0', or pin fhir.resources<7.0.0 for Pydantic v1 compatibility (which supports Python 3.8+).

breaking Default FHIR version changed from R4B to R5 in fhir.resources 7.x+. Top-level imports now return R5 models. ↓

fix For R4B resources, import from fhir.resources.R4B.* subpackage instead of top-level fhir.resources.*.

breaking Pydantic v2 migration changed validation and serialization methods. .parse_obj() and .json() are replaced. ↓

fix Use Patient.model_validate(data) instead of Patient.parse_obj(data), and patient.model_dump_json() instead of patient.json().

gotcha The package installs as a namespace package (fhir.resources). Do not create your own 'fhir' package in your project or it will shadow the library. ↓

fix Avoid naming your own modules or packages 'fhir' to prevent import conflicts.

gotcha FHIR resource validation is strict by default. Missing required fields or invalid value sets will raise ValidationError. ↓

fix Catch pydantic.ValidationError and inspect e.errors() for details on which fields failed validation.

gotcha resourceType field must match the class name exactly. Passing resourceType='patient' (lowercase) will raise a validation error. ↓

fix Always use the exact CamelCase resourceType, e.g. 'Patient', 'Observation', 'Bundle'.

Install

pip install 'fhir.resources[r4]'

Install compatibility verified last tested: 2026-05-12

python os / libc variant status wheel install import disk

3.10 alpine (musl) r4 - - 0.56s 52.2M

3.10 alpine (musl) fhir.resources - - 0.56s 52.2M

3.10 slim (glibc) r4 - - 0.41s 52M

3.10 slim (glibc) fhir.resources - - 0.39s 52M

3.11 alpine (musl) r4 - - 0.80s 57.2M

3.11 alpine (musl) fhir.resources - - 0.82s 57.2M

3.11 slim (glibc) r4 - - 0.67s 57M

3.11 slim (glibc) fhir.resources - - 0.70s 57M

3.12 alpine (musl) r4 - - 0.95s 47.8M

3.12 alpine (musl) fhir.resources - - 0.96s 47.8M

3.12 slim (glibc) r4 - - 0.91s 48M

3.12 slim (glibc) fhir.resources - - 0.91s 48M

3.13 alpine (musl) r4 - - 0.54s 47.3M

3.13 alpine (musl) fhir.resources - - 0.53s 47.3M

3.13 slim (glibc) r4 - - 0.53s 47M

3.13 slim (glibc) fhir.resources - - 0.53s 47M

3.9 alpine (musl) r4 - - - -

3.9 alpine (musl) fhir.resources - - - -

3.9 slim (glibc) r4 - - - -

3.9 slim (glibc) fhir.resources - - - -

Imports

Patient
wrong
```
from fhir_resources import Patient
```
correct
```
from fhir.resources.patient import Patient
```
The package uses a namespace package 'fhir.resources'. Each resource type is in its own module with a lowercase name.
Patient (R4)
wrong
```
from fhir.resources.patient import Patient  # this gives R5
```
correct
```
from fhir.resources.R4B.patient import Patient
```
To use FHIR R4B resources, import from fhir.resources.R4B subpackage. Default top-level imports are R5.
Patient (STU3)
```
from fhir.resources.STU3.patient import Patient
```
STU3 resources live under the fhir.resources.STU3 subpackage.
Bundle
```
from fhir.resources.bundle import Bundle
```
Each FHIR resource is its own module. Import the class with the CamelCase name from the lowercase module.

Quickstart verified last tested: 2026-05-12

Create, validate, and serialize a FHIR Patient resource using Pydantic v2 methods.

from fhir.resources.patient import Patient

# Create from dict
patient_data = {
    "resourceType": "Patient",
    "id": "example",
    "active": True,
    "name": [
        {
            "use": "official",
            "family": "Doe",
            "given": ["John"]
        }
    ],
    "gender": "male",
    "birthDate": "1990-01-01"
}

patient = Patient.model_validate(patient_data)
print(patient.name[0].family)  # 'Doe'

# Serialize back to FHIR JSON
print(patient.model_dump_json(indent=2))

# Parse from JSON string
json_str = patient.model_dump_json()
patient2 = Patient.model_validate_json(json_str)
print(patient2.id)  # 'example'