Skip to content

Using the fw ingest dicom Command

Introduction

The ingest dicom command reads through directories of DICOM files and uses the DICOM header information to group them into the correct Acquisitions and Sessions in Flywheel. The ingest dicom command requires Flywheel CLI version 11.0 or later.

This article explains the optional arguments for the ingest dicom command. See this article for directions on how to run the ingest dicom command.

Usage

fw ingest dicom [path to dicom data] [group id] [project label] [optional arguments]

Instruction Steps

Required Arguments

Required Argument Description
SRC The path to the DICOM data you wish to import
GROUP_ID Enter an existing Flywheel group ID or create a new group ID
PROJECT_LABEL Enter an existing Flywheel project label or create a new project

By default, Flywheel uses the following DICOM tags to label data. If your scans are missing these tags,  the --subject and --session flags are also required to successfully upload your data.

Required DICOM tag Flywheel label CLI flag to use if missing
PatientID Subject label --subject <subjectLabel>
StudyDescription Session label --session <sessionLabel>

If your scans do have values for the PatientID and StudyDescription fields, you do not need to use these flags. However, you can use them to change the default labels for the subjects and sessions.

fw ingest dicom ~/Documents/MyData/Study001 mygroup "A project" --subject 01 --session 01

Optional Arguments

If you are using multiple optional arguments in your command, consider creating a config file. See the article for more information on creating and using a config file.

Ingest DICOM

Optional Argument Description
--force-scan Try to parse all files as DICOM files regardless of the DICM prefix (default: false). Consider using --include "\*".
--session LABEL Override value for the session label.
--subject LABEL Override value for the subject label.

Ingest General

Optional Argument Description
--compression-level The compression level to use for packfiles -1 by default. 0 for storage. A higher compression level number means more compression.
--de-identify De-identify DICOM files, e-files and p-files prior to upload. Applies custom de-identification when used with a deid-profile set in a configuration file. By default, it will apply the minimal de-identification to DICOM files:

* Remove PatientID, PatientName, and PatientBirthdate
* PatientAge convert to months.
--deid-profile NAME Use the De-identify profile by name. Use this flag if you have multiple de-ID profiles in a single config.
--detect-duplicates Flywheel scans both the source dataset and any data already in the Flywheel project. Flywheel looks for the following:

* File path conflict in the source dataset - File path in the upload dataset is not unique
* File path conflict in Flywheel - file already exists
Duplicate StudyInstanceUID in source dataset
* Duplicate StudyInstanceUID in Flywheel - UID already exists
 Duplicate SeriesInstanceUID in the source dataset
* Duplicate SeriesInstanceUID in Flywheel - UID already exists
* Duplicate SOPInstanceUID in series
--detect-duplicates-project DETECT_DUPLICATES_PROJECT Specify one or multiple project paths to use for detecting duplicates.
--copy-duplicates Upload duplicate files to a new project when using --detect-duplicates.

The project created for the duplicates will be named [target project label]_[TimestampOfIngest]. The duplicates project will have the same permissions as the original destination project. No additional project artifacts need to be copied (gear rules, data views, description, etc).
--enable-project-files Enable file uploads to a project container.
--encodings ENCODINGS Set character encoding aliases. E.g. `win_1251=cp1251``.
--exclude PATTERN Patterns of filenames to exclude (default: none). For example:

* Exclude a single file: --exclude="ReadMe.md"
* Exclude all files of a specific filetype: --exclude="*.md"
--exclude-dirs PATTERN Patterns of directories to exclude (default: none).

For example:--exclude-dirs="Sub-01" excludes all files and folder within the Sub-01 folder. This means the following directories would not be uploaded: * Sub-01/Sess01
* Sub-01/Sess2/Acq02
-g ID, --group ID The ID of the group if not in the folder structure.
--ignore-unknown-tags Ignore unknown dicom tags when parsing dicom files (default: false).
--include PATTERN [PATTERN ...] Patterns of filenames to include (default: none).

For example:
* Include a single file: --include="participants.csv"
* Include all files of a filetype: --include="*.dcm"
--include-dirs PATTERN [PATTERN ...] Patterns of directories to include (default: none).

For example:
* --include-dirs="OHM/101-10*".
The regex wildcard means that this would include the directories like:
* OHM/101-105
* OHM/101-106
* OHM/101-1011.
Note: When S3 bucket is configured as source, this flag does not support regex wildcard match, only "starts with."
--load-subject PATH Load subjects from the specified file.
--no-audit-log Skip uploading audit log to the target projects.
--require-project Proceed with the ingest process only if the resolved group and project exists (default: false).

By default, Flywheel creates a new group or project if an existing group ID or project label does not match what you designated in your command or template. This means if you mistype the group ID or project label, your data will be uploaded in the wrong location. Use this flag to make sure your data is only uploaded to existing groups and projects.
--skip-existing Looks at filenames for files already in your project, and skip import of files with the same filename. (default: false).
--symlinks Follow symbolic links that resolve to directories (default: false).

Reporting Config

Applicability

These config options are only available either when using --cluster mode with the --follow argument or when using local worker.

Optional Argument Description
--save-audit-log PATH Save audit log to the specified path on the current machine (default: none)
--save-deid-log PATH Save de-id log to the specified path on the current machine (default: none)
--save-subjects PATH Save subjects to the specified file (default: none)

Cluster Config

Applicability

These config options apply when using a cluster to ingest data.

Optional Argument Description
--cluster CLUSTER Ingest cluster url (default: none)
-f, --follow Follow the progress of the ingest (default: false)

Worker Config

Applicability

These config options are only available when using local worker (--cluster is not defined).

Optional Argument Description
--jobs JOBS Number of concurrent jobs to run (e.g. scan jobs), ignored when using cluster (default: 4)
--sleep-time SECONDS Number of seconds to wait before trying to get a task (default: 1)
--max-tempfile MAX_TEMPFILE Maximum in-memory tempfile size, in MB, or 0 to always use disk (default: 50)

General

Optional Argument Description
-h, --help Show help message and exit.
-C PATH, --config-file Specify configuration options via config file.*
--no-config Do NOT load the default configuration file.
-y, --yes Assume the answer is yes to all prompts.
--ca-certs CA_CERTS Path to a local Certificate Authority certificate bundle file. This option may be required when using a private Certificate Authority.
--timezone TIMEZONE Set the effective local timezone to use when uploading data.
-q, --quiet Squelch log messages to the console.
-d, --debug Turn on debug logging.
-v, --verbose Get more detailed output.

* Learn more about how to create this file.

Common Errors

Common Ingest Errors

For authentication, permissions, network issues, and other errors common to all ingest commands, see the Ingest Troubleshooting Guide.

"Invalid DICOM - missing UID tag" (SC02)

Cause: DICOM files are missing required UID tags (StudyInstanceUID, SeriesInstanceUID, or SOPInstanceUID).

Solution:

  • Verify files are valid DICOM format using a DICOM viewer
  • Files may be corrupted or incomplete
  • Check if files were properly exported from imaging equipment
  • Contact your imaging center if files consistently lack UIDs

"Empty/invalid DICOM file"

Cause: DICOM file has no parsable headers or is empty.

Solution:

  • Verify files are actually DICOM format (not renamed JPEGs, etc.)
  • Check for file corruption during transfer
  • Use --force-scan to attempt parsing files without the DICM prefix
  • Remove invalid files from the source directory

Duplicate Detection Errors (DD01-DD12)

Cause: When using --detect-duplicates, the CLI found duplicate or conflicting DICOM UIDs.

Solution:

  • Review the audit log for specific duplicate detection error codes and affected files
  • See Duplicate Detection for detailed explanations of each error code
  • Use --detect-duplicates-override DD04 DD07 to downgrade specific errors to warnings
  • Clean up duplicate data in source directory before re-importing

Advanced Options

For large-scale or specialized ingest workflows, the following advanced features are available:

Cluster Ingest

Speed up large imports by using Flywheel's ingest cluster to process data directly from cloud storage (S3, GCS, Azure).

When to use: Importing datasets larger than 100 GB or when faster upload speeds are needed.

Learn more about Cluster Ingest

Duplicate Detection

Automatically detect and handle duplicate DICOM files during ingest to avoid redundant uploads.

When to use: Re-importing data that may partially overlap with existing data, or ensuring data integrity.

Learn more about Duplicate Detection

Audit Logging

Generate detailed audit logs of all ingest operations for compliance and troubleshooting.

When to use: Regulated environments requiring detailed import tracking, or when troubleshooting failed imports.

Learn more about Audit Logging

S3 Credentials Setup

Configure credentials for the ingest cluster to access your S3 buckets.

When to use: Required for cluster ingest from private S3 buckets.

Learn more about S3 Credentials

See Also

Related Commands:

Data Management:

De-identification:

Troubleshooting: