pyxnat

library1.6.4pypypi✓ verified 89d ago

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.

http-networking data

pip install pyxnat

github ↗package ↗

INSTALL

IMPORT

SIG · PYXNAT

pyxnat

http-networkingpythonv1.6.4

Install

2.7s avg

Import

679ms

Disk

32MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.6.4 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.920 runs

installs and imports cleanly · install 0.0s · import 0.716s · 34.3MB

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 2.7s · import 0.643s · 35MB

32MB installed

● package 32MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Interface

✓ from pyxnat import Interface

✗ import pyxnat; interface = pyxnat.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.

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}")

Debug

Known issues

breakingPython 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.

affects: < 1.6.4

gotchaDirectly 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.

affects: All versions

deprecatedThe `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.

affects: >= 1.6

gotchaThe 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.

affects: All versions using external XNAT instances

Errors

Common errors & fixes

pyxnat.core.errors.DatabaseError: pyxnat.file.put failure: URI: ... status code: 500

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: ...

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

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

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.

Upgrade

Version history

1.6.4latest on PyPI · released Nov 6, 2025

Audit

Dependencies

requestsrequiredRequired for making HTTP requests to the XNAT REST API.

python-lxmlrequiredRecommended for XML parsing; earlier versions may work but 4.3.2+ is advised.

Agent activity

6 hits · last 30 days

node

Resources

githubhttps://github.com/pyxnat/pyxnat ↗

packagehttps://pypi.org/project/pyxnat/ ↗