python-orthanc-api-client

A python client to ease using the Orthanc Rest API.

Functionalities are very limited now ! Backward compat will break a lot in the near future !

PyOrthanc or python-orthanc-api-client?

Another project pyorthanc is quite similar to python-orthanc-api-client.

If you are wondering which one to use, please refer to this discussion. tl;dr: this project is mainly an internal tool made public. pyorthanc is more feature complete and its documentation is much better.

Installation:

pip3 install orthanc-api-client

Examples:

from orthanc_api_client import OrthancApiClient, ResourceType, InstancesSet
import datetime

orthanc_a = OrthancApiClient('http://localhost:8042', user='orthanc', pwd='orthanc')
orthanc_b = OrthancApiClient('http://localhost:8043', user='orthanc', pwd='orthanc')

if not orthanc_a.wait_started(timeout=20):
    print("Orthanc has not started after 20 sec")

if not orthanc_a.is_alive():
    print("Could not connect to Orthanc, check it is running")

# upload files/folders
orthanc_a.upload_folder('/home/o/files', ignore_errors=True)
instances_ids = orthanc_a.upload_file('/home/o/files/a.dcm')
instances_ids = orthanc_a.upload_file('/home/o/files/a.zip')
with open('/home/o/files/a.dcm', 'rb') as f:
    instances_ids = orthanc_a.upload(f.read())
orthanc_a.upload_files_dicom_web(['/home/o/files/a.dcm'])
    
# list all resources ids
all_patients_ids = orthanc_a.patients.get_all_ids()
all_studies_ids = orthanc_a.studies.get_all_ids()
all_series_ids = orthanc_a.series.get_all_ids()
all_instances_ids = orthanc_a.instances.get_all_ids()

# show some daily stats
orthanc_a.studies.print_daily_stats(from_date=datetime.date(2022, 2, 4), to_date=datetime.date(2022, 2, 8))
orthanc_a.series.print_daily_stats() # show last 8 days per default
orthanc_a.instances.print_daily_stats()

# get system stats
print(f"This Orthanc stores {orthanc_a.get_statistics().studies_count} studies for a total of {orthanc_a.get_statistics().total_disk_size_mb} MB")

# instances methods
dicom_file = orthanc_a.instances.get_file(orthanc_id=all_instances_ids[0])
instances_ids = orthanc_b.upload(buffer=dicom_file)
study_id = orthanc_b.instances.get_parent_study_id(instances_ids[0])

# access study info & simplified tags
study = orthanc_b.studies.get(study_id)
patient_id = study.patient_main_dicom_tags.get('PatientID')
study_description = study.main_dicom_tags.get('StudyDescription')
dicom_id = study.dicom_id

# get the ids of all the studies of a patient
studies = orthanc_a.patients.get_studies_ids(patient_id)

# access metadata
orthanc_a.instances.set_string_metadata(orthanc_id=all_instances_ids[0], 
                                 metadata_name=1024, 
                                 content='my-value')

# access tags
tags = orthanc_a.instances.get_tags(orhtanc_id=all_instances_ids[0])
patient_name = tags['PatientName']
patient_id = tags['0010,0020']
patient_sex = tags['0010-0040']

# anonymize
anon_study_id = orthanc_b.studies.anonymize(
    orthanc_id=study_id,
    keep_tags=['PatientName'],
    replace_tags={
        'PatientID': 'ANON'
    },
    force=True,
    delete_original=False
)

# find locally in Orthanc
study_id = orthanc_a.studies.lookup(dicom_id='1.2.3.4')
study_id = orthanc_a.studies.lookup(dicom_id='1.2.3.4', filter="Study")

studies = orthanc_a.studies.find(query={
    'PatientName': 'A*', 
    'StudyDate': '20220101-20220109'
})

# find in a remote modality
remote_studies = orthanc_a.modalities.query_studies(
    from_modality='pacs',
    query={'PatientName': 'A*', 'StudyDate': '20220101-20220109'}
)
orthanc_a.modalities.retrieve_study(
    from_modality=remote_studies[0].remote_modality_id,
    dicom_id=remote_studies[0].dicom_id
)

# send to a remote modality
orthanc_a.modalities.send(
    target_modality='orthanc-b',
    resources_ids=[study_id],
    synchronous=True
)

# send to a remote peer (synchronous)
orthanc_a.peers.send(
    target_peer='orthanc-b',
    resources_ids=[study_id]
)

# send using transfer plugin
orthanc_a.transfers.send(
    target_peer='orthanc-b',
    resources_ids=[study_id],
    resource_type=ResourceType.STUDY,
    compress=True
)

# work with a snapshot of a study
instances_set = InstancesSet.from_study(orthanc_a, study_id=study_id)
modified_set = instances_set.modify(
        replace_tags={
            'InstitutionName' : 'MY'
        },
        keep_tags=['SOPInstanceUID', 'SeriesInstanceUID', 'StudyInstanceUID'],
        force=True,
        keep_source=True # we are not changing orthanc IDs -> don't delete source since it is the same as destination
    )

# send instance_set
orthanc_a.transfers.send(  
    target_peer='orthanc-b',
    resources_ids=modified_set.instances_ids,
    resource_type=ResourceType.STUDY,
    compress=True
)

# delete after send
modified_set.delete()

helpers methods

import datetime
from orthanc_api_client import helpers, OrthancApiClient

dicom_date = helpers.to_dicom_date(datetime.date.today())
standard_date = helpers.from_dicom_date(dicom_date)

# for tests:
o = OrthancApiClient('http://localhost:8042', user='orthanc', pwd='orthanc')
helpers.wait_until(lambda: len(o.instances.get_all_ids() > 50), timeout=30)

dicom_date = helpers.get_random_dicom_date(date_from=datetime.date(2000, 1, 1),
                                           date_to=datetime.date.today())
dicom_file = helpers.generate_test_dicom_file(width=128,
                                              height=128,
                                              tags={
                                                  "PatientName": "Toto",
                                                  "StudyInstanceUID": "123"
                                              })

upload a folder to Orthanc

from orthanc_api_client import OrthancApiClient

o = OrthancApiClient('http://localhost:8042', user='orthanc', pwd='orthanc')
o.upload_folder('/home/o/files', ignore_errors=True)

running from inside an Orthanc python plugin

from orthanc_api_client import OrthancApiClient
import orthanc
import json

orthanc_client = None

def OnChange(changeType, level, resource):
    global orthanc_client

    if changeType == orthanc.ChangeType.ORTHANC_STARTED:
        orthanc.LogWarning("Starting python plugin")

        # at startup, use the python SDK direct access to the Rest API to retrieve info to pass to the OrthancApiClient that is using 'requests'
        system = json.loads(orthanc.RestApiGet('/system'))
        api_token = orthanc.GenerateRestApiAuthorizationToken()

        orthanc_client = OrthancApiClient(
            orthanc_root_url=f"http://localhost:{system['HttpPort']}",
            api_token=api_token
        )
        ...

orthanc.RegisterOnChangeCallback(OnChange)

Metadata

Release files for orthanc-api-client 0.25.3

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for orthanc-api-client 0.25.3
File	Size	Uploaded
orthanc_api_client-0.25.3.tar.gz	56.2 kB	Jul 7, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for orthanc-api-client 0.25.3
File	Interpreter	ABI	Platform	Reset
orthanc_api_client-0.25.3-py3-none-any.whl 48.8 kB Jul 7, 2026	Python 3	none	any	Details

Total release size: 105.0 kB

Release files / orthanc_api_client-0.25.3.tar.gz

Download URL	orthanc_api_client-0.25.3.tar.gz
Size	56.2 kB
Tags	Source
SHA-256 checksum How to use checksums	`a9c33b56bc83581c0a4b73cd57c346b2a71e4c3d7835ba0e59e78e83bcd779a3`
BLAKE2b-256 checksum How to use checksums	`84a1e094781daee26b26bdf8f03e574a3c05f3790c1c65eb3784f5e46aa07343`
Upload date	Jul 7, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.13.12`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/orthanc-team/python-orthanc-api-client
Publishing commit: github.com/orthanc-team/python-orthanc-api-client/tree/a7205b91878f67080295042c784db863d0ef8ee0

Workflow

Publishing configuration: github.com/orthanc-team/python-orthanc-api-client/blob/a7205b91878f67080295042c784db863d0ef8ee0/.github/workflows/release.yml
Publishing logs: github.com/orthanc-team/python-orthanc-api-client/actions/runs/28870347842/attempts/1

Artifact

Subject: orthanc_api_client-0.25.3.tar.gz
SHA-256 checksum: a9c33b56bc83581c0a4b73cd57c346b2a71e4c3d7835ba0e59e78e83bcd779a3 Verifying attestations

Release files / orthanc_api_client-0.25.3-py3-none-any.whl

Download URL	orthanc_api_client-0.25.3-py3-none-any.whl
Size	48.8 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`75a2e3c01183516785d4e59f58d969c74f32dbe04775d282dc20e5450a675732`
BLAKE2b-256 checksum How to use checksums	`1090e141c1571ab52908aef68f97948c74ea7b6ea5c879df37263150c0c7dfb4`
Upload date	Jul 7, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.13.12`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/orthanc-team/python-orthanc-api-client
Publishing commit: github.com/orthanc-team/python-orthanc-api-client/tree/a7205b91878f67080295042c784db863d0ef8ee0

Workflow

Publishing configuration: github.com/orthanc-team/python-orthanc-api-client/blob/a7205b91878f67080295042c784db863d0ef8ee0/.github/workflows/release.yml
Publishing logs: github.com/orthanc-team/python-orthanc-api-client/actions/runs/28870347842/attempts/1

Artifact

Subject: orthanc_api_client-0.25.3-py3-none-any.whl
SHA-256 checksum: 75a2e3c01183516785d4e59f58d969c74f32dbe04775d282dc20e5450a675732 Verifying attestations