Skip to content

Installation⚓︎

There are several ways to install dcm2bids.

Containers⚓︎

We provide a container image that includes both dcm2niix and dcm2bids as well as pydeface and the BIDS validator. You can install it using Docker or Apptainer/Singularity.

1
2
export VERSION=3.2.0
docker pull unfmontreal/dcm2bids:${VERSION}

1
2
export VERSION=3.2.0
apptainer pull dcm2bids.sif docker://unfmontreal/dcm2bids:${VERSION}

Installing binary executables⚓︎

From dcm2bids>=3.0.0, we provide binaries for macOS, Windows and Linux (debian-based and rhel-based).

They can easily been downloaded from the release page.

Once downloaded, you should be able to extract the dcm2bids, dcm2bids_scaffold, and dcm2bids_helper files and use them with the full path.

1
2
3
4
sam:~/software$ curl -fLO https://github.com/unfmontreal/dcm2bids/releases/latest/download/dcm2bids_debian-based_3.0.rc1.tar.gz
sam:~/software$ tar -xvf dcm2bids_debian-based*.tar.gz
sam:~/software$ cd ../data
sam:~/data$ ~/software/dcm2bids_scaffold -o new-bids-project

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
sam:~/software$ curl -fLO https://github.com/unfmontreal/dcm2bids/releases/latest/download/dcm2bids_debian-based_3.0.0rc1.tar.gz
% Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                              Dload  Upload   Total   Spent    Left  Speed
0     0    0     0    0     0      0      0 --:--:-- --:--:-- --:--:--     0
0     0    0     0    0     0      0      0 --:--:-- --:--:-- --:--:--     0
100 40.6M  100 40.6M    0     0  23.2M      0  0:00:01  0:00:01 --:--:-- 36.4M

sam:~/software$ tar -xvf dcm2bids_debian-based*.tar.gz
dcm2bids
dcm2bids_helper
dcm2bids_scaffold

sam:~/software$ cd ../data

sam:~/data$ ~/software/dcm2bids_scaffold -o new-bids-project
INFO    | --- dcm2bids_scaffold start ---
INFO    | Running the following command: /home/sam/software/dcm2bids_scaffold -o new-bids-project
INFO    | OS version: Linux-5.15.0-76-generic-x86_64-with-glibc2.31
INFO    | Python version: 3.10.12 | packaged by conda-forge | (main, Jun 23 2023, 22:40:32) [GCC 12.3.0]
INFO    | dcm2bids version: 3.0.rc1
INFO    | Checking for software update
INFO    | Currently using the latest version of dcm2bids.
INFO    | The files used to create your BIDS directory were taken from https://github.com/bids-standard/bids-starter-kit.

INFO    | Tree representation of new-bids-project/
INFO    | new-bids-project/
INFO    | ├── code/
INFO    | ├── derivatives/
INFO    | ├── sourcedata/
INFO    | ├── tmp_dcm2bids/
INFO    | │   └── log/
INFO    | │       └── scaffold_20230716-122220.log
INFO    | ├── .bidsignore
INFO    | ├── CHANGES
INFO    | ├── dataset_description
INFO    | ├── participants.json
INFO    | ├── participants.tsv
INFO    | └── README
INFO    | Log file saved at new-bids-project/tmp_dcm2bids/log/scaffold_20230716-122220.log
INFO    | --- dcm2bids_scaffold end ---

Installing using pip or conda⚓︎

Before you can use dcm2bids, you will need to get it installed. This page guides you through a minimal, typical dcm2bids installation workflow that is sufficient to complete all dcm2bids tasks.

We recommend to skim-read the full page before you start installing anything considering there are many ways to install software in the Python ecosystem which are often dependent on the familiarity and preference of the user.

We offer recommendations at the bottom of the page that will take care of the whole installation process in one go and make use of a dedicated environment for dcm2bids.

You just want the installation command?

You can use the binaries provided with each release (starting with dcm2bids>=3)

If you are used to installing packages, you can get it from PyPI or conda:

pip install dcm2bids

conda install -c conda-forge dcm2bids

Dependencies⚓︎

Python⚓︎

As dcm2bids is a Python package, the first prerequisite is that Python must be installed on the machine you will use dcm2bids. You will need Python 3.8 or above to run dcm2bids properly.

If you are unsure what version(s) of Python is available on your machine, you can find out by opening a terminal and typing python --version or python. The former will output the version directly in the terminal while the latter will open an interactive Python shell with the version displayed in the first line.

1
2
sam:~$ python --version
Python 3.10.4

1
2
3
4
sam:~$ python
Python 3.10.4 | packaged by conda-forge | (main, Mar 24 2022, 17:39:04) [GCC 10.3.0] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> exit()

If your system-wide version of Python is lower 3.8, it is okay. We will make sure to use a higher version in the isolated environment that will be created for dcm2bids. The important part is to verify that Python is installed.

If you are a beginning user in the Python ecosystem, the odds are that you have installed Anaconda, which contains all Python versions so you should be good. If you were not able to find out which version of Python is installed on your machine or find Anaconda on your machine, we recommend that you install Python through Anaconda.

Should I install Anaconda or Miniconda?

If you unsure what to install read this section describing the differences between Anaconda and Miniconda to help you choose.

dcm2niix⚓︎

dcm2niix can also be installed in a variety of ways as seen on the main page of the software.

Whether you want to install the latest compiled executable directly on your machine is up to you but you have to make sure you can call the software from any directory. In other words, you have to make sure it is included in your $PATH. Otherwise, dcm2bids won't be able to run dcm2niix for you. That's why we recommend to install it at the same time in the dedicated environment.

As you can see, dcm2niix is available through conda so that is the approach chosen in this guide. We will benefit from the simplicity of installing all software from the same located at. Steps to install dcm2niix are included in the next section.

Recommendations⚓︎

We recommend to install all the dependencies at once when installing dcm2bids on a machine or server. As mentioned above the minimal installation requires only dcm2bids, dcm2niix and Python >= 3.8. For ease of use and to make sure we have a reproducible environment, we recommend to use a dedicated environment through conda or, for those who have it installed, Anaconda. Note that you don't need to use specifically them to use dcm2bids, but it will make your life easier.

More info on conda

Conda is an open-source package management system and environment management system that runs on Windows, macOS, and Linux. Conda quickly installs, runs, and updates packages and their dependencies. Conda easily creates, saves, loads, and switches between environments on your local computer. The conda package and environment manager is included in all versions of Anaconda and Miniconda. - conda docs

But I use another package/env management system, what do I do?

Of course you can use your preferred package/env management system, whether it is venv, virtualenv, pyenv, pip, poetry, etc. This guide was built on the basis that no previous knowledge is required to install and learn dcm2bids by so providing a simple way to install dcm2bids without having to worry about the rest.

I already created an environment for my project, what do I do?

You can update your environment either by:

  1. installing dcm2bids while your environment is active like any package; or
  2. adding dcm2bids to the dependencies and updating your environment

Here's an example with conda after updating an environment.yml file:

1
conda env update --file environment.yml --prune

Install dcm2bids⚓︎

From now on, it is assumed that conda (or Anaconda) is installed and correctly setup on your computer as it is the easiest way to install dcm2bids and its dependencies on any OS. We assume that if you want to install it in a different way, you have enough skills to do it on your own.

If you installed Anaconda and want to use the graphical user interface (GUI), you can follow the steps as demonstrated below and only read the steps until the end of the installation guide.

Create your environment with the Anaconda Navigator GUI
  1. Open Anaconda Navigator
  2. Click on Environments, then the + button at the bottom ana_navigator_1
  3. Enter the name of the environment, it can be anything. You can call it dcm2bids then select Python ana_navigator_2
  4. Click on the new dcm2bids environment, then on Channels
  5. If you only see defaults, click on Add... then enter conda-forge then click on Update channels ana_navigator_3
  6. You now need to add the two main software, so you need to search for them in the top right corner. You should see them appear as soon as you right dcm2. You can select both at the same time.
    • If you don't seem them, you probabble need to select All channels instead of Installed. ana_navigator_4
  7. It will ask you to install a bunch of packages, Apply. ana_navigator_5
  8. You environment should now be ready, click on the green circle with the white arrow to start the environment. A terminal window should open. ana_navigator_6
  9. You should see the name of your environment (dcm2bids) to the left. You can now test that dcm2bids works. ana_navigator_7

We could install all the software one by one using a series of command:

1
2
conda install -c conda-forge dcm2bids
conda install -c conda-forge dcm2niix

But this would install the software in the main environment instead of a dedicated one, assuming none were active. This could have atrocious dependencies issues in the long-term if you want to install other software.

Create environment.yml⚓︎

That is exactly why dedicated environments were invented. To help creating dedicated environments, we can create a file, often called environment.yml, which is used to specify things such as the dependencies that need to be installed inside the environment.

To create such a file, you can use any code editor or your terminal to write or paste the information below, and save it in your project directory with the name environment.yml:

You can create a project directory anywhere on your computer, it does not matter. You can create dcm2bids-proj if you need inspiration.

1
2
3
4
5
6
7
name: dcm2bids
channels:
  - conda-forge
dependencies:
  - python>=3.8
  - dcm2niix
  - dcm2bids

In short, here's what the fields mean:

  • The name: key refers to the name of the dedicated environment. You will have to use this name to activate your environment and use software installed inside. The name is arbitrary, you can name it however you want.
  • The channels: key tells conda where to look for the declared dependencies. In our case, all our dependencies are located on the conda-forge channel.
  • The dependencies: key lists all the dependencies to be installed inside the environment. If you are creating an environment for your analysis project, this is where you would list other dependencies such as nilearn, pandas, and especially as pip since you don't want to use the pip outside of your environment Note that we specify python>=3.8 to make sure the requirement is satisfied for dcm2bids as the newer version of dcm2bids may face issue with Python 3.6 and below.

Now that all the dependencies have been specified, it is time to create the new conda environment dedicated to dcm2bids! 🎉

Create conda environment + install dcm2bids⚓︎

Open a terminal and go in the directory where you put the environment.yml run this command:

1
conda env create --file environment.yml

If the execution was successful, you should see a message similar to:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
sam:~/dcm2bids-proj$ nano environment.yml
sam:~/dcm2bids-proj$ conda env create --file environment.yml
Collecting package metadata (repodata.json): done
Solving environment: |done

Downloading and Extracting Packages
future-0.18.2        | 738 KB    | ########################################## | 100%
Preparing transaction: done
Verifying transaction: done
Executing transaction: done
#
# To activate this environment, use
#
#     $ conda activate dcm2bids
#
# To deactivate an active environment, use
#
#     $ conda deactivate

Activate environment⚓︎

Last step is to make sure you can activate1 your environment by running the command:

1
conda activate dcm2bids

⚠️ Remember that dcm2bids here refer to the name given specified in the environment.yml.

1
2
sam:~/dcm2bids-proj$ conda activate dcm2bids
(dcm2bids) sam:~/dcm2bids-proj$

You can see the environment is activated as a new (dcm2bids) appear in front of the username.

Verify that dcm2bids works⚓︎

Finally, you can test that dcm2bids was installed correctly by running the any dcm2bids command such as dcm2bids --help:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
(dcm2bids) sam:~/dcm2bids-proj$ dcm2bids --help
usage: dcm2bids [-h] -d DICOM_DIR [DICOM_DIR ...] -p PARTICIPANT [-s SESSION]
                -c CONFIG [-o OUTPUT_DIR]
                [--auto_extract_entities | --do_not_reorder_entities]
                [--bids_validate] [--force_dcm2bids] [--skip_dcm2niix]
                [--clobber] [-l {DEBUG,INFO,WARNING,ERROR,CRITICAL}] [-v]

Reorganising NIfTI files from dcm2niix into the Brain Imaging Data Structure

options:
  -h, --help            show this help message and exit
  -d DICOM_DIR [DICOM_DIR ...], --dicom_dir DICOM_DIR [DICOM_DIR ...]
                        DICOM directory(ies) or archive(s) (tar, tar.bz2, tar.gz or zip).
  -p PARTICIPANT, --participant PARTICIPANT
                        Participant ID.
  -s SESSION, --session SESSION
                        Session ID. []
  -c CONFIG, --config CONFIG
                        JSON configuration file (see example/config.json).
  -o OUTPUT_DIR, --output_dir OUTPUT_DIR
                        Output BIDS directory. [/home/runner/work/Dcm2Bids/Dcm2Bids]
  --auto_extract_entities
                        If set, it will automatically try to extract entityinformation [task, dir, echo] based on the suffix and datatype. [False]
  --do_not_reorder_entities
                        If set, it will not reorder entities according to the relative ordering indicated in the BIDS specification and use the order defined in custom_entities by the user.
                        Cannot be used with --auto_extract_entities.  [False]
  --bids_validate       If set, once your conversion is done it will check if your output folder is BIDS valid. [False]
                        bids-validator needs to be installed check: https://github.com/bids-standard/bids-validator#quickstart
  --force_dcm2bids      Overwrite previous temporary dcm2bids output if it exists.
  --skip_dcm2niix       Skip dcm2niix conversion. Option -d should contains NIFTI and json files.
  --clobber             Overwrite output if it exists.
  -l {DEBUG,INFO,WARNING,ERROR,CRITICAL}, --log_level {DEBUG,INFO,WARNING,ERROR,CRITICAL}
                        Set logging level to the console. [INFO]
  -v, --version         Report dcm2bids version and the BIDS version.

Documentation at https://unfmontreal.github.io/Dcm2Bids/

Voilà, you are ready to use dcm2bids or at least move onto the tutorial!!

Go to the Tutorial section

Go to the How-to section

Summary of the steps⚓︎

In sum, installing dcm2bids is quite easy if you know how to install Python packages. The easiest way to install it is to follow the steps below using conda but it is also possible to use other software, including containers:

  • Create an environment.yml file with dependencies

    • Content:
      1
2
3
4
5
6
7
      name: dcm2bids
channels:
    - conda-forge
dependencies:
    - python>=3.8
    - dcm2niix
    - dcm2bids

  • Create conda environment

    • conda env create --file environment.yml
  • Activate conda environment
    • conda activate dcm2bids
  • Verify a dcm2bids command
    • dcm2bids --help
  • Consult how-to guides or follow the tutorial

  1. To get out of a conda environment, you have to deactivate it with the conda deactivate command. ↩

Last update: 2024-07-26
Created: 2022-04-17