Installation

Get BiomiX 3.0 running

BiomiX 3.0 uses Docker to ensure a stable, reproducible environment across all platforms. The launcher scripts handle everything automatically, no command-line knowledge required.

0

Install Docker

BiomiX 3.0 requires Docker to be installed on your system. We recommend Docker Engine on Linux/Ubuntu, which is the environment BiomiX 3.0 has been built and tested for. New to Docker? Follow our Docker installation guide.

A local installation without Docker is still possible using the legacy install scripts. See the legacy installation section at the bottom of this page for details.

1

Download the BiomiX launcher

Download the launcher script for your operating system from the BiomiX GitHub repository. Place it in a folder of your choice, it will automatically create a biomix_shared folder nearby for your input data and results.

BiomiX_Windows.zip Windows, contains .bat and .ps1 BiomiX_Start.sh Linux, run from terminal BiomiX-Launcher-1.0.0.dmg macOS, open and install
๐Ÿ“ฆ

All launchers are also available in the BiomiX GitHub repository under the launchers/ folder.

2

Launch BiomiX

The launcher will automatically pull all required Docker modules on first run and open the BiomiX interface in your browser. Select your platform below.

  1. Make sure Docker Desktop is open and running (look for the whale icon in the system tray).
  2. Double-click BiomiX_Start.bat, a setup window will appear.
  3. Choose the folder where your input data is located and where results will be saved.
  4. Optionally, enter your NCBI API key to enhance PubMed search in the biological interpretation module. This is not required, BiomiX works fully without it.
  5. Click Start. BiomiX will open automatically in your browser at http://localhost:3838.
๐Ÿ’ก

Keep the terminal window open while using BiomiX. Closing it will stop the application.

  1. Make sure Docker Engine is running: sudo systemctl start docker
  2. Open a terminal, navigate to the folder containing BiomiX_Start.sh, and make it executable (first time only): 
    chmod +x BiomiX_Start.sh
  3. Run the launcher: 
    ./BiomiX_Start.sh
  4. When prompted, choose your data folder and optionally enter your NCBI API key (optional, enhances PubMed search in the interpretation module).
  5. BiomiX will open in your browser at http://localhost:3838.
๐Ÿ’ก

Keep the terminal open while using BiomiX. Press Ctrl+C to stop it when done.

  1. Make sure Docker Desktop is open and running (look for the whale icon in the menu bar).
  2. Open the downloaded BiomiX-Launcher-1.0.0.dmg and follow the installation steps.
  3. Launch the BiomiX app from your Applications folder. A setup window will appear.
  4. Choose the folder where your input data is located and where results will be saved.
  5. Optionally, enter your NCBI API key to enhance PubMed search in the biological interpretation module. This is not required, BiomiX works fully without it.
  6. Click Start. BiomiX will open automatically in your browser at http://localhost:3838.
๐Ÿ’ก

Keep the launcher window open while using BiomiX. Closing it will stop the application.

For advanced users who prefer to pull each module manually. biomix_gui and biomix-base are always required. Add only the analysis modules relevant to your workflow.

ModulePull commandRequired
biomix_gui
BiomiX graphical interface, Shiny frontend
docker pull ghcr.io/biomix-consortium/biomix_gui:latest
 Always required
biomix-base
Core R environment used by all analysis modules
docker pull ghcr.io/biomix-consortium/biomix-base:latest
 Always required
biomix-transcriptomics
Transcriptomics single-omics pipeline
docker pull ghcr.io/biomix-consortium/biomix-transcriptomics:latest
 Optional
biomix-methylomics
Methylomics single-omics pipeline
docker pull ghcr.io/biomix-consortium/biomix-methylomics:latest
 Optional
biomix-metabolomics
Metabolomics single-omics pipeline
docker pull ghcr.io/biomix-consortium/biomix-metabolomics:latest
 Optional
biomix-mofa
MOFA integration method
docker pull ghcr.io/biomix-consortium/biomix-mofa:latest
 Optional
biomix-snf
SNF integration method
docker pull ghcr.io/biomix-consortium/biomix-snf:latest
 Optional
biomix-nemo
NEMO integration method
docker pull ghcr.io/biomix-consortium/biomix-nemo:latest
 Optional
biomix-diablo
DIABLO integration method
docker pull ghcr.io/biomix-consortium/biomix-diablo:latest
 Optional
biomix-pramigo Soon
PRAMIGO integration method, not yet released
 Coming soon Optional
๐Ÿ’ก

Once pulled manually, launch the interface with: docker run -p 3838:3838 -v /path/to/data:/shared ghcr.io/biomix-consortium/biomix_gui:latest

๐Ÿšง

PRAMIGO will be released as a separate module shortly after BiomiX 3.0. The launcher will update automatically once it becomes available.

Need help?

If you run into issues during installation, please open an issue on the consortium's issue tracker or contact us directly at cristian.iperi@univ-brest.fr.

โš ๏ธ

This installation method is no longer actively maintained and may be unstable due to dependency conflicts across platforms. It is preserved for users who cannot use Docker. For all new installations, the Docker-based approach above is strongly recommended.

The local installation creates isolated Python (pyenv) and R (renv) environments and installs all required packages into them, without affecting your system-wide installations. It relies on PyQt5 for the graphical interface.

Download the BiomiX 2.5 release archive from the BiomiX2.5 GitHub repository, unzip it, then run the five installation scripts in order from the _INSTALL/ folder.

Run each script in sequence from the _INSTALL/ folder. Each step must complete successfully before moving to the next.

Step 1 of 5 โ€” Python environment
01_BiomiX_install_Python.sh
Creates an isolated Python environment and installs the PyQt5 interface and its dependencies.
bash _INSTALL/01_BiomiX_install_Python.sh
Step 2 of 5 โ€” R environment
02_BiomiX_install_R.sh
Creates an isolated R environment via renv, separate from any system-wide R installation.
bash _INSTALL/02_BiomiX_install_R.sh
Step 3 of 5 โ€” Core R packages
03_BiomiX_install_R_Packages.sh
Installs the core R packages required for single-omics analysis and MOFA/DIABLO integration.
bash _INSTALL/03_BiomiX_install_R_Packages.sh
Step 4 of 5 โ€” SNF and NEMO packages
04_BiomiX_install_Extension_R_SNF_NEMO.sh
Installs the R packages required for the SNF and NEMO integration methods.
bash _INSTALL/04_BiomiX_install_Extension_R_SNF_NEMO.sh
Step 5 of 5 โ€” MintTea packages
05_BiomiX_install_Extension_R_MintTea.sh
Installs the R packages required for the MintTea integration method.
bash _INSTALL/05_BiomiX_install_Extension_R_MintTea.sh
Launch BiomiX
Once all five steps are complete, launch BiomiX with:
./LaunchApp_BiomiX_Linux.sh

Double-click each .bat file in order from the _INSTALL\ folder. Each step must complete successfully before moving to the next.

Step 1 of 5 โ€” Python environment
01_BiomiX_install_Python.bat
Creates an isolated Python environment and installs the PyQt5 interface and its dependencies.
Step 2 of 5 โ€” R environment
02_BiomiX_install_R.bat
Creates an isolated R environment via renv.
Step 3 of 5 โ€” Core R packages
03_BiomiX_install_R_Packages.bat
Installs core R packages for single-omics analysis and MOFA/DIABLO integration.
Step 4 of 5 โ€” SNF and NEMO packages
04_BiomiX_install_Extension_R_SNF_NEMO.bat
Installs R packages for the SNF and NEMO integration methods.
Step 5 of 5 โ€” MintTea packages
05_BiomiX_install_Extension_R_MintTea.bat
Installs R packages for the MintTea integration method. On Windows, this step is available only via the .sh script under WSL.
Launch BiomiX
Once all steps are complete, double-click LaunchApp_BiomiX_Windows.bat to start BiomiX.

Troubleshooting the local installation

Dependency issues are common with the local installation. The most reliable fix is to open an R session inside the BiomiX renv environment, activate renv, and install the missing packages manually.

ModuleNotFoundError: No module named 'package'

Activate the BiomiX Python environment and install the missing package:

pip install package-name
Error in library("Package"): no package named "Package"

Open R inside the BiomiX renv environment and install the missing package:

R
# Inside R:
renv::activate()
renv::install("PackageName")
fontconfig / freetype error (Linux) 
sudo apt-get install libfontconfig1-dev