Skip to content

Overview

The Flywheel software development kit (SDK) is a Python library that provides programmatic access to the Flywheel platform. It wraps the Flywheel application programming interface (API), enabling you to interact with your Flywheel instance directly from Python scripts, notebooks, and automated workflows.

The SDK supports Python 3.10 and later.

Why Use the SDK?

The SDK is designed for users who need to go beyond what the Flywheel web interface offers — whether that means automating repetitive tasks, processing large datasets, or building custom integrations.

Common use cases include:

  • Automation: Run batch operations, schedule recurring tasks, and build data pipelines that operate without manual intervention.
  • Data Management: Perform bulk uploads and downloads, extract and update metadata across many containers, and curate datasets programmatically.
  • Analysis Workflows: Execute gears, aggregate results, and build quality control (QC) pipelines across projects and subjects.
  • Custom Integrations: Connect Flywheel with external tools, databases, or processing systems using Python.
  • Data Exploration: Search and filter containers, generate reports, and extract structured data across groups and projects.

Key Capabilities

The SDK provides access to the full range of Flywheel platform features, including:

  • Container Management: Create, read, update, and delete containers across the Flywheel hierarchy, including groups, projects, subjects, sessions, and acquisitions.
  • Metadata: Read and modify file metadata, including custom info, tags, and notes.
  • Finders and Queries: Use finders and advanced query filters to locate containers and files across your Flywheel instance.
  • Data Aggregation: Build DataViews, work with collections, and generate structured reports across your data.
  • Gear Execution: Schedule gear jobs, monitor job status, and retrieve analysis outputs.
  • Permissions: Manage user access and project-level permissions programmatically.

SDK vs UI vs CLI

The Flywheel platform offers three primary interfaces. Choosing the right one depends on your workflow and goals.

Interface Best For
Web user interface (UI) Interactive browsing, manual data operations, visual inspection
Command-line interface (CLI) File import and export, gear development, admin tasks
Python SDK Complex automation, data pipelines, custom integrations

Use the web UI when you want to browse your data, inspect files visually, or perform one-off manual operations without writing code.

Use the CLI for file import and export workflows that fit naturally into shell scripts, or for gear development and administrative tasks.

Use the SDK when you need programmatic control — for example, to loop over thousands of sessions, apply consistent metadata transformations, trigger gear executions, or integrate Flywheel into a larger data processing pipeline.

Documentation Updates

The Flywheel SDK documentation is currently in the midst of an overhaul to provide increased coverage of SDK capabilities, improved organization, and a wealth of tips and tricks. During this interim period, all previously-existing documentation is provided in the Archive.

Next Steps

Whether you are new to the Flywheel SDK or returning after a Flywheel update, the following resources will help you find what you need.

  • Getting Started: Install the SDK, connect to Flywheel, and make your first requests.
  • Core Concepts: Learn foundational SDK techniques, paired with more in-depth examples.
  • Gear Concepts (Coming Soon): Use the SDK to find and inspect gears, run and monitor jobs, and work with analyses.
  • Clinical Concepts (Coming Soon): Leverage the SDK to manage tasks, forms, and other clinical-focused workflows.
  • Admin Concepts (Coming Soon): Manage permissions and settings, investigate usage and audit trail, and more.
  • API Reference: The complete API reference is auto-generated and available to navigate and search.

What's New

If you are a returning SDK user who may not follow every Flywheel release note, here are some recent capabilities worth exploring:

  • Subject, Session, and Acquisition Smart Copy: Performing a Smart Copy of a single subject, session, or acquisition to an existing destination is now possible with the Flywheel SDK. The SDK functions support the same filters available with Project Smart Copy, and can detect label conflicts and update labels as part of the copy operation. (Release: Flywheel Core 20.5)

Additional Resources

  • Flywheel homepage: Learn about Flywheel - the company, the platform, and how we can help you reach your medical imaging and analysis goals.
  • Flywheel product documentation: Full platform documentation covering the web interface, administration, and integrations.

Flywheel also maintains multiple Python libraries that leverage or pair with the Flywheel SDK to assist with common Flywheel-related tasks:

  • fw-gear: A Flywheel-maintained Python library for developing and running Flywheel gears.
  • fw-curation: A Flywheel-maintained Python library for data curation workflows.
  • fw-file: A Flywheel-maintained Python library for reading and writing medical file types, with a focus on DICOM.