Installation

Prerequisites

  • Python 3.11 or later

  • UV package manager (recommended) or pip

  • Git

Install with pip

# Clone the repository
git clone https://github.com/SoftmatterLMU-RaedlerGroup/pyama.git
cd pyama

# Create and activate virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -e pyama/

Verify Installation

# Start the API server
uv run pyama serve --port 8000 --reload

# In another terminal, run the React/Electron client
cd pyama-react
bun install  # or npm install
bun run dev

Development Dependencies

For development, you’ll also want to install the dev dependencies:

# With UV
uv sync --all-extras

# With pip
pip install pytest ruff ty

Docker (API Server)

Run the pyama API server in a Docker container:

cd pyama

# Build and run with GPU (default - Linux with NVIDIA)
docker compose up --build

# Or CPU-only (Mac or no GPU)
docker compose --profile cpu up --build pyama-cpu

# Server available at http://localhost:8765
# Health check: curl http://localhost:8765/health

Volume Mounts

Configure data access in docker-compose.yml:

volumes:
  - ~/data:/data        # Microscopy files (use /data/... in API requests)
  - ~/results:/results  # Output directory (use /results/... in API requests)
  - pyama-db:/root/.pyama  # Persist task database

Important: Symlinks in mounted directories won’t work. Mount the actual data locations instead.

GPU Support

The container uses PyTorch 2.10.0 with CUDA 13.0:

  • GPU (default): docker compose up - requires NVIDIA Container Toolkit on Linux

  • CPU: docker compose --profile cpu up pyama-cpu - works on Mac or systems without GPU

Troubleshooting

Python Version

Make sure you’re using Python 3.11 or later. Check with:

python --version

UV Installation

Install UV following the official guide at https://docs.astral.sh/uv/

Web Frontend Dependencies

PyAMA React client requires Node.js plus either Bun or npm:

  • Install Bun (recommended): https://bun.sh/

  • Or use npm: bundled with Node.js