Skip to main content

Orthanc REST API python wrapper with additional utilities

Project description

ci documentation PyPI - Version PyPI - Downloads


PyOrthanc is a python client for the Orthanc REST API, which fully wraps all the methods of the REST API. Additionally, it provides many utility functions to interact with an Orthanc instance.

See the full documentation here

Install PyOrthanc using pip:

pip install pyorthanc

Then use the client. If Orthanc is running locally, the default URL is http://localhost:8042.

import pyorthanc

client = pyorthanc.Orthanc('http://localhost:8042', username='orthanc', password='orthanc')
patient_ids = client.get_patients()

Interact with connected modalities

import pyorthanc

modality = pyorthanc.Modality(client, 'MY_MODALITY')
assert modality.echo()

# C-Find on modality
response = modality.query({'Level': 'Study', 'Query': {'PatientID': '*'}})

# C-Move to target modality
modality.move(response['ID'], {'TargetAet': 'target_modality'})

Find patients

patients = pyorthanc.find_patients(client, {'PatientID': '*P001'})
for patient in patients:
    for study in patient.studies:
        for series in study.series:
            for instance in series.instances:
                pydicom_ds = instance.get_pydicom()

Resources (Patient, Study, Series, Instance) can be easily anonymized.

import pyorthanc

orthanc_patient_id = client.get_patients()[0]
patient = pyorthanc.Patient(orthanc_patient_id, client)

Waiting the for the anonymization process:

new_patient = patient.anonymize()
new_patient_with_given_patient_id = patient.anonymize(
   replace={'PatientID': 'TheNewPatientID'},
   force=True  # Needed when changing PatientID/StudyInstanceUID/SeriesInstanceUID/SOPInstanceUID

For long-running job (i.e. large patient) or to submit many anonymization jobs at the same time, use

job = patient.anonymize_as_job()
job.state  # You can follow the job state

job.wait_until_completion() # Or just wait on its completion
new_patient = pyorthanc.Patient(job.content['ID'], client)

Notes on versioning

PyOrthanc has been rewritten almost entirely from 0.*.*. The new Orthanc client is now automatically generated from The version *.*. of PyOrthanc will follow Orthanc version (e.g. pyorthanc 1.11.* is generated from the API specification of Orthanc 1.11.*).

You can still use the old client with

from pyorthanc.deprecated.client import Orthanc
from pyorthanc.deprecated.client_1_11_3 import Orthanc

Note that due to automatic generation some method names may be less clear. However, the automatic generation allows PyOrthanc to cover all the routes of the API of Orthanc.


If you publish using PyOrthanc, we kindly ask that you credit us. PyOrthanc can be found on Zenodo : .


You can contribute to this project with the following steps:

  1. First, fork the project on Github
  2. Clone the project
    git clone<your-github-username>/pyorthanc
    cd pyorthanc
  3. Create a poetry environment (this project use the poetry for dependency management)
    peotry install 
  4. Make a new git branch where you will apply the changes
    git checkout -b your-branch-name
    Now you can make your changes
  5. Once done, git add, git commit and git push the changes.
  6. Make a Pull Request from your branch to the

Project details

Download files

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

Source Distribution

pyorthanc-1.12.2.tar.gz (148.4 kB view hashes)

Uploaded source

Built Distribution

pyorthanc-1.12.2-py3-none-any.whl (161.7 kB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page