{"id":7647,"library":"pyxnat","title":"pyxnat","description":"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.","status":"active","version":"1.6.4","language":"en","source_language":"en","source_url":"https://github.com/pyxnat/pyxnat","tags":["XNAT","medical imaging","neuroscience","data management","imaging data","REST API"],"install":[{"cmd":"pip install pyxnat","lang":"bash","label":"Install pyxnat via pip"}],"dependencies":[{"reason":"Required for making HTTP requests to the XNAT REST API.","package":"requests","optional":false},{"reason":"Recommended for XML parsing; earlier versions may work but 4.3.2+ is advised.","package":"python-lxml","optional":false}],"imports":[{"note":"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.","wrong":"import pyxnat; interface = pyxnat.Interface(...)","symbol":"Interface","correct":"from pyxnat import Interface"}],"quickstart":{"code":"import os\nfrom pyxnat import Interface\n\nXNAT_HOST = os.environ.get('XNAT_HOST', 'https://central.xnat.org')\nXNAT_USER = os.environ.get('XNAT_USER', '')\nXNAT_PASSWORD = os.environ.get('XNAT_PASSWORD', '')\n\nif not (XNAT_USER and XNAT_PASSWORD): \n    print(\"Please set XNAT_USER and XNAT_PASSWORD environment variables.\")\n    print(\"Or set XNAT_HOST if not using central.xnat.org.\")\nelse:\n    try:\n        # Connect to the XNAT instance\n        interface = Interface(server=XNAT_HOST, user=XNAT_USER, password=XNAT_PASSWORD)\n        print(f\"Successfully connected to {XNAT_HOST} as {XNAT_USER}\")\n\n        # List projects\n        projects = interface.select.projects().get()\n        print(\"\\nAvailable projects:\")\n        for project_id in projects:\n            print(f\"- {project_id}\")\n\n        # Disconnect\n        interface.disconnect()\n        print(\"\\nDisconnected from XNAT.\")\n\n    except Exception as e:\n        print(f\"Error connecting to XNAT or listing projects: {e}\")","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"< 1.6.4"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Migrate testing setup from `nose` to `pytest` for `pyxnat`-related test cases.","message":"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.","severity":"deprecated","affected_versions":">= 1.6"},{"fix":"Use a different public XNAT instance (like NITRC/IR) or a locally deployed XNAT instance (e.g., via Docker) for testing and development.","message":"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.","severity":"gotcha","affected_versions":"All versions using external XNAT instances"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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.","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.","error":"pyxnat.core.errors.DatabaseError: pyxnat.file.put failure: URI: ... status code: 500"},{"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).","cause":"The credentials (username or password) provided for connecting to the XNAT server are incorrect or lack the necessary permissions for the requested operation.","error":"Error connecting to XNAT or listing projects: 401 Client Error: Unauthorized for url: ..."},{"fix":"Add `from pyxnat import Interface` at the top of your Python script or interactive session before attempting to use `Interface`.","cause":"The `Interface` class was used without being correctly imported from the `pyxnat` library.","error":"NameError: name 'Interface' is not defined"},{"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.","cause":"The XNAT server URL provided is malformed, missing the protocol (http/https), hostname, port, or XNAT application name (e.g., '/xnat').","error":"Error connecting to XNAT or listing projects: Invalid URL 'http://server_ip:port/xnat': No host in url"}]}