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)

Project links

Data verified by PyPI on Jun 28, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.25.3)

2 maintainers

PyPI data
Data sourced directly from PyPI's database.
Avatar for amazy from gravatar.com amazy Avatar for bcrickboom from gravatar.com bcrickboom

Credits

Author: Orthanc Team

GitHub Statistics

Data verified by PyPI on Jun 28, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License

GNU Lesser General Public License v3 (LGPLv3)

Requires

Python <4, >=3.8

Provides Extra

dev test

Tags

orthanc dicom rest api

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

orthanc_api_client-0.25.2.tar.gz (56.2 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

orthanc_api_client-0.25.2-py3-none-any.whl (48.8 kB view details)

Uploaded Python 3

File details

Details for the file orthanc_api_client-0.25.2.tar.gz.

File metadata

  • Download URL: orthanc_api_client-0.25.2.tar.gz
  • Upload date:
  • Size: 56.2 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for orthanc_api_client-0.25.2.tar.gz
Algorithm Hash digest
SHA256 c89bb0a0d204774a1acfd54fc0e5f6a31e37003b191e41db8a4125417b104ba4
MD5 2938b265b4d61b433d9529ed96e8b2d8
BLAKE2b-256 7173d0fde2e9f22957bcdf7be8699c2b18981b65b5b11426b3dbe6a92f9dd809

See more details on using hashes here.

Provenance

The following attestation bundles were made for orthanc_api_client-0.25.2.tar.gz:

Publisher: release.yml on orthanc-team/python-orthanc-api-client

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file orthanc_api_client-0.25.2-py3-none-any.whl.

File metadata

File hashes

Hashes for orthanc_api_client-0.25.2-py3-none-any.whl
Algorithm Hash digest
SHA256 e9d2e4bcd0064b0a7a7e83b7ab6d56281b31ceb69d48805faba5151e27cf6779
MD5 9fe91587c9c18df7de88c4be2ba0bf63
BLAKE2b-256 e3dd767e15829c3f3c08504da015c35e6947f577128937c4640cd16e30c4ab42

See more details on using hashes here.

Provenance

The following attestation bundles were made for orthanc_api_client-0.25.2-py3-none-any.whl:

Publisher: release.yml on orthanc-team/python-orthanc-api-client

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

0.25.3

2 files

This release

0.25.2 This release

2 files

0.25.1

2 files

0.25.0

2 files

0.24.3

2 files

0.24.2

2 files

0.24.1

2 files

0.24.0

2 files

0.23.0

2 files

0.22.2

2 files

0.22.1

2 files

0.21.0

2 files

0.20.1

2 files

0.20.0

2 files

0.19.0

2 files

0.18.8

2 files

0.18.7

2 files

0.18.6

2 files

0.18.5

2 files

0.18.4

2 files

0.18.3

2 files

0.18.2

2 files

0.18.1

2 files

0.18.0

2 files

0.17.0

2 files

0.16.3

2 files

0.16.2

2 files

0.16.1

2 files

0.16.0

2 files

0.15.3

2 files

0.15.2

2 files

0.15.1

2 files

0.15.0

2 files

0.14.14

2 files

0.14.13

2 files

0.14.12

2 files

0.14.11

2 files

0.14.10

2 files

0.14.9

2 files

0.14.8

2 files

0.14.7

2 files

0.14.6

2 files

0.14.5

2 files

0.14.4

2 files

0.14.3

2 files

0.14.2

2 files

0.14.1

2 files

0.14.0

2 files

0.13.8

2 files

0.13.7

2 files

0.13.6

2 files

0.13.5

2 files

0.13.4

2 files

0.13.3

2 files

0.13.2

2 files

0.13.1

2 files

0.12.2

2 files

0.12.1

2 files

0.12.0

2 files

0.11.8

2 files

0.11.7

2 files

0.11.6

2 files

0.11.5

2 files

0.11.4

2 files

0.11.3

2 files

0.11.2

2 files

0.11.1

2 files

0.11.0

2 files

0.10.2

2 files

0.10.1

2 files

0.10.0

2 files

0.9.1

2 files

0.9.0

2 files

0.8.3

2 files

0.8.2

2 files

0.8.1

2 files

0.8.0

2 files

0.7.1

2 files

0.7.0

2 files

0.6.1

2 files

0.6.0

2 files

0.5.8

2 files

0.5.7

2 files

0.5.6

2 files

0.5.5

2 files

0.5.4

2 files

0.5.3

2 files

0.5.2

2 files

0.5.1

2 files

0.5.0

2 files

0.4.1

2 files

0.4.0

2 files

0.3.12

2 files

0.3.11

2 files

0.3.10

2 files

0.3.9

2 files

0.3.8

2 files

0.3.7

2 files

0.3.6

2 files

0.3.5

2 files

0.3.4

2 files

0.3.3

2 files

0.3.2

2 files

0.3.1

2 files

0.3.0

2 files

0.2.3

2 files

0.2.2

2 files

0.2.1

2 files

0.2.0

2 files

0.1.9

2 files

0.1.8

2 files

0.1.7

2 files

0.1.6

2 files

0.1.5

2 files

0.1.4

2 files

0.1.3

2 files

0.1.2

2 files

0.1.1

2 files

0.1.0

2 files

0.0.8

2 files

0.0.7

2 files

0.0.6

2 files

0.0.5

2 files

0.0.4

2 files

0.0.3

2 files

0.0.2

2 files

0.0.1

2 files

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page