pyxnat

1.6.4 · active · verified Thu Apr 16

pyxnat is an open source, BSD-licenced library providing a programmatic interface with XNAT, an extensible management system for imaging data and related information. It uses the RESTful Web services provided by XNAT to enable easier interaction through a simple and consistent API using Python. The library is actively maintained, with the latest version 1.6.4 released as a maintenance and compatibility update, typically seeing several minor releases per year.

Common errors

```
pyxnat.core.errors.DatabaseError: pyxnat.file.put failure: URI: ... status code: 500
```
cause This error typically indicates that a resource you are trying to access or modify (e.g., upload a file to a non-existent resource, or the target URI is incorrect) does not exist on the XNAT server, or there's an issue with the file content/path during an upload.

fix Verify that the resource (project, subject, experiment, scan, resource label) you are targeting actually exists on the XNAT server. For file uploads, ensure the local file path is correct and the file exists, and that the server-side resource structure is correctly specified.
```
Error connecting to XNAT or listing projects: 401 Client Error: Unauthorized for url: ...
```
cause The credentials (username or password) provided for connecting to the XNAT server are incorrect or lack the necessary permissions for the requested operation.

fix Double-check your `XNAT_USER` and `XNAT_PASSWORD` (or other credential sources) for typos. Ensure the user has the appropriate permissions on the XNAT server to access the requested data (e.g., list projects).
```
NameError: name 'Interface' is not defined
```
cause The `Interface` class was used without being correctly imported from the `pyxnat` library.

fix Add `from pyxnat import Interface` at the top of your Python script or interactive session before attempting to use `Interface`.
```
Error connecting to XNAT or listing projects: Invalid URL 'http://server_ip:port/xnat': No host in url
```
cause The XNAT server URL provided is malformed, missing the protocol (http/https), hostname, port, or XNAT application name (e.g., '/xnat').

fix Ensure the `server` argument to `Interface` is a complete and correct URL, including the protocol (e.g., `https://my.xnat.org:8443/xnat`). Consult your XNAT administrator for the exact URL.

Warnings

breaking Python 2.7, 3.6, 3.7, and 3.8 support has been officially terminated in recent releases. Version 1.5 dropped 2.7 and 3.6. Version 1.6 dropped 3.7. Version 1.6.4 dropped 3.8.
Fix: Ensure your environment uses Python 3.9 or 3.10. Newer Python versions (e.g., 3.11, 3.12, 3.13) may work but are not officially tested until explicitly stated in release notes.
gotcha Directly embedding credentials (username/password) in scripts is insecure. When creating an `Interface` object, omitting credentials will prompt the user for input, or you can use configuration files.
Fix: Use environment variables (as in the quickstart), an `.xnatPass` configuration file (e.g., `~/.xnatPass`), or let `Interface` prompt for credentials interactively. Use `interface.save_config()` to create config files.
deprecated The `nose` testing framework was replaced by `pytest` in `pyxnat` version 1.6. Developers relying on `nose` for testing custom modules interacting with `pyxnat` will need to update their test suites.
Fix: Migrate testing setup from `nose` to `pytest` for `pyxnat`-related test cases.
gotcha The public XNAT Central instance, previously used for CI testing and examples, has been decommissioned. Older tutorials or example code referencing `central.xnat.org` may no longer work as expected.
Fix: Use a different public XNAT instance (like NITRC/IR) or a locally deployed XNAT instance (e.g., via Docker) for testing and development.

Install

pip install pyxnat Install pyxnat via pip

Imports

Interface
wrong:
```
import pyxnat; interface = pyxnat.Interface(...)
```
correct:
```
from pyxnat import Interface
```
While 'import pyxnat' works, direct import of Interface is the common and recommended practice to avoid verbose calls and potential ambiguity with other pyxnat submodules.

Quickstart

This quickstart demonstrates how to establish a connection to an XNAT server using the `Interface` class and then retrieve a list of available projects. It uses environment variables for secure credential handling.

import os
from pyxnat import Interface

XNAT_HOST = os.environ.get('XNAT_HOST', 'https://central.xnat.org')
XNAT_USER = os.environ.get('XNAT_USER', '')
XNAT_PASSWORD = os.environ.get('XNAT_PASSWORD', '')

if not (XNAT_USER and XNAT_PASSWORD): 
    print("Please set XNAT_USER and XNAT_PASSWORD environment variables.")
    print("Or set XNAT_HOST if not using central.xnat.org.")
else:
    try:
        # Connect to the XNAT instance
        interface = Interface(server=XNAT_HOST, user=XNAT_USER, password=XNAT_PASSWORD)
        print(f"Successfully connected to {XNAT_HOST} as {XNAT_USER}")

        # List projects
        projects = interface.select.projects().get()
        print("\nAvailable projects:")
        for project_id in projects:
            print(f"- {project_id}")

        # Disconnect
        interface.disconnect()
        print("\nDisconnected from XNAT.")

    except Exception as e:
        print(f"Error connecting to XNAT or listing projects: {e}")

view raw JSON →