Installation

m2m can be installed using Docker (recommended for simplicity) or locally with Python.

Quick Start

Option 1: Docker (Recommended)

The easiest way to use m2m - no Python installation needed! Pre-built images are automatically built and published to Docker Hub.

Using the pre-built image (no git clone needed):

# Create data directories
mkdir -p data/input data/output

# Run the web interface directly
docker run -p 8501:8501 -v $(pwd)/data:/data linumuqam/m2m:latest

# Access the web interface at http://localhost:8501

Using docker-compose (recommended for development):

# Clone the repository
git clone https://github.com/linum-uqam/m2m.git
cd m2m

# Create data directories
mkdir -p data/input data/output

# Start with Docker Compose
docker-compose up

# Access the web interface at http://localhost:8501

Requirements:

Docker Desktop or Docker Engine
Docker Compose (optional, for docker-compose method)

Benefits:

✅ No Python installation required
✅ Works identically on all platforms (Linux, macOS, Windows)
✅ All dependencies pre-installed
✅ Isolated environment
✅ Pre-built images updated automatically on each release

Option 2: Local Python Installation

For development or if you prefer a local installation:

# Clone the repository
git clone https://github.com/linum-uqam/m2m.git
cd m2m

# Create a virtual environment with Python 3.11 (recommended)
python3.11 -m venv .venv

# Activate the virtual environment
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install the package
pip install --upgrade pip
pip install -e .

Requirements:

Python 3.9, 3.10, or 3.11 (Python 3.11 recommended)
Python 3.12+ is not supported due to AllenSDK dependency constraints
pip (usually comes with Python)
Git

Platform Notes:

Linux: Fully supported
macOS: Fully supported (Intel and Apple Silicon)
Windows: Most features work, but antspyx may have limited support. Use Docker for full compatibility.

Option 3: Using Conda (Optional)

If you prefer conda for Python version management:

# Create a conda environment with Python 3.11
conda create -n m2m python=3.11 pip
conda activate m2m

# Install m2m using pip
cd m2m
pip install -e .

Note

Conda is no longer required. The package uses standard pip + venv installation for simplicity.

Running m2m

Docker Usage

Web Interface:

docker-compose up
# Access at http://localhost:8501

Run m2m Scripts:

docker run --rm \
  -v $(pwd)/scripts:/scripts:ro \
  -v $(pwd)/data:/data:rw \
  linumuqam/m2m:latest \
  python /scripts/m2m_download_template.py --help

Interactive Python Session:

docker run --rm -it \
  -v $(pwd)/data:/data \
  linumuqam/m2m:latest \
  python

Bash Shell:

docker run --rm -it \
  -v $(pwd)/scripts:/scripts \
  -v $(pwd)/data:/data \
  linumuqam/m2m:latest \
  bash

Local Installation Usage

Web Interface:

source .venv/bin/activate  # Activate your virtual environment
streamlit run app/m2m_main_page.py

Python API:

import m2m
# Your code here

Command Line Scripts:

source .venv/bin/activate
m2m_download_template.py --help

Update

Docker

To update the Docker image:

docker-compose down
git pull
docker-compose build --no-cache
docker-compose up

Local Installation

To update your local installation:

git pull
source .venv/bin/activate  # or: conda activate m2m
pip install --upgrade -e .

Troubleshooting

NumPy Version Conflicts

The Allen SDK requires numpy < 1.24. If you encounter numpy version conflicts:

pip install "numpy>=1.23,<1.24"
pip install -e .

Docker Build Issues

If Docker build fails or takes too long:

# Clear Docker cache and rebuild
docker system prune -a
docker-compose build --no-cache

Port Already in Use

If port 8501 is already in use, modify docker-compose.yml:

ports:
  - "8502:8501"  # Use port 8502 instead

Then access at http://localhost:8502

Platform-Specific Issues

Windows (WSL):

For native Windows, we recommend using Docker. Alternatively, use WSL2:

# Install WSL (run as administrator)
wsl --install

For more details, see the official WSL documentation

macOS Apple Silicon:

All dependencies work on Apple Silicon (M1/M2/M3). Python 3.11 recommended.

Linux:

Ensure you have development tools:

# Debian/Ubuntu
sudo apt-get update
sudo apt-get install python3.11 python3.11-venv python3.11-dev build-essential

Getting Help

GitHub Issues: https://github.com/linum-uqam/m2m/issues
Documentation: https://m2m.readthedocs.io/