Skip to content


Switch branches/tags

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time



Test Updates:

V2 V2


Butterfly Installation

In your system shell, enter the below code blocks in order:

  1. Download and open the source code

    git clone
    cd butterfly
    • Developers: Make and Open a virtualenv
  2. Prepare to install

    pip install -U pip
    pip install -r requirements.txt
  3. Install bfly command

    pip install -e .

Now, you should be able to run the bfly command!

Running Butterfly

Make sure bfly --help shows the below

usage: bfly [-h] [-e exp] [-o out] [port]

Butterfly Version 2.0

positional arguments:
  port               port >1024 for hosting this server (Default 2001)

optional arguments:
  -h, --help         show this help message and exit
  -e exp, --exp exp  path to load config yaml or folder with all data 
  -o out, --out out  path to save output yaml listing all --exp data
  • If you simply run bfly without arguments,
    • The data loads from paths in ~/.rh-config.yaml
    • The server starts on http://localhost:2001
  • If you run bfly 2017,
    • The server starts on http://localhost:2017
  • If you run bfly -e ~/my-config.yaml
    • The data loads from paths in ~/my-config.yaml
  • If your run bfly -e ~/data -o ~/.rh-config.yaml
    • The data loads from the ~/data folder
    • The data paths save to ~/.rh-config.yaml

The RH Conifg (~/.rh-config.yaml)

The default path to this file is ~/.rh-config.yaml You can change this path by entering this to the shell:

export RH_CONFIG_FILENAME=~/my-config.yaml

After that, running bfly works like bfly -e ~/my-config.yaml

The RH config file structure:

The default values are given here:

    # HTTP port to listen on
    port: 2001
    # Max size of the image cache in MB
    max-cache-size: 1024
    # Serve only files under a list of paths
        - /
    # Restart the server on code change
    developer-mode: no

Let's say the user username has these folders in ~/data:

  • dense
    • excellent
      • synapse-segmentation.h5
      • neuron-segmentation.h5
    • synapse-training.h5
    • neuron-training.h5
    • raw-image.h5

This must be mapped to a system butterfly understands:

  • experiment root
    • sample data
      • dataset excellent
        • channel synapse-segmentation.h5
        • channel neuron-segmentation.h5
      • dataset dense
        • channel synapse-training.h5
        • channel neuron-training.h5
        • channel raw-image.h5

The user username can save this mapping to ~/my-config.yaml with this command:

bfly -e ~/data -o ~/my-config.yaml

Then, the user can edit ~/my-config.yaml by hand to make bfly serve on port 2017 with up to 2 GiB of RAM used to cache images. The resulting ~/my-config.yaml would then look like this:

    port: 2001
    max-cache-size: 2048
        - name: root
            - name: data
                    - name: dense
                          - name: neuron-training.h5
                            path: /home/username/data/dense/neuron-training.h5
                          - name: raw-image.h5
                            path: /home/username/data/dense/raw-image.h5
                          - name: synapse-training.h5
                            path: /home/username/data/dense/synapse-training.h5
                    - path: /home/username/data/dense
                    - name: excellent
                          - name: neuron-segmentation.h5
                            path: /home/username/data/dense/excellent/neuron-segmentation.h5
                          - name: synapse-segmentation.h5
                            path: /home/username/data/dense/excellent/synapse-segmentation.h5
                    - path: /home/username/data/dense/excellent

Finally, this file at /home/username/my-config.yaml will be used by default whenever the bfly command is run so long as username remembers to type this in their shell:

export RH_CONFIG_FILENAME=~/my-config.yaml