Installation Guide 📦

[!TIP] Quick start: If you're just exploring FlowyML, run pip install "flowyml[all]" and you're ready to go. Come back to this page when you need production-grade deployment. To add support for interactive GUI: pip install "flowyml[ui]".

System Requirements

Python 3.10+ --- Recommended for best performance and type safety features.
OS Agnostic --- Native support for Linux, macOS, and Windows (WSL2 recommended).
8GB+ RAM --- Recommended for handling large ML models and intensive pipelines.

Why FlowyML? We focus on lightweight core and extensible extras. Install only what you need for your production environment to keep your Docker images slim and secure.

Installation Options

Choose the installation that matches your use case:

Basic Installation — Local Development Only

Install FlowyML core package:

pip install flowyml

What you get: Core pipeline orchestration, local artifact storage, metadata tracking.

Use this when: You're prototyping locally and don't need cloud deployment or the web UI yet.

Full Installation — Everything Included (Recommended)

pip install "flowyml[all]"

What you get: Web UI, cloud integrations, ML framework support, everything.

Use this when: You want to try all FlowyML features without reinstalling. This is the recommended approach for new users.

Optional Dependencies — Pick What You Need

For minimal installations or specific production setups, install only what you need:

ML Framework Support

# TensorFlow/Keras automatic tracking
pip install "flowyml[tensorflow]"

# PyTorch integration
pip install "flowyml[pytorch]"

# Scikit-learn utilities
pip install "flowyml[sklearn]"

Use this when: You're building Docker images and want to minimize size, or you only use specific frameworks.

Cloud Platform Support

# Google Cloud Platform (Vertex AI, GCS, Container Registry)
pip install "flowyml[gcp]"

# AWS support (SageMaker, S3, ECR)
pip install "flowyml[aws]"

# Azure support (Azure ML, Blob Storage, ACR)
pip install "flowyml[azure]"

Use this when: You're deploying to cloud and want cloud-specific features like managed orchestration (Vertex AI), cloud storage (GCS/S3), and container registries.

Web UI & API Server

pip install "flowyml[ui]"

What you get: The visualization dashboard, REST API,real-time monitoring.

Use this when: You need the visual interface for debugging or monitoring, or building tools that integrate with FlowyML's API.

Development

Install development dependencies:

pip install flowyml[dev]

Combining Extras

You can combine multiple extras:

# TensorFlow + GCP
pip install flowyml[tensorflow,gcp]

# All ML frameworks + GCP
pip install flowyml[tensorflow,pytorch,sklearn,gcp]

# Everything including UI
pip install flowyml[all]

From Source

git clone https://github.com/UnicoLab/FlowyML.git
cd FlowyML
pip install -e ".[all]"

Docker

# Basic image
docker pull flowyml/flowyml:latest

# With TensorFlow
docker pull flowyml/flowyml:latest-tf

# With PyTorch
docker pull flowyml/flowyml:latest-torch

# Full image
docker pull flowyml/flowyml:latest-full

Verification

Verify installation:

import flowyml
print(flowyml.__version__)

# Check available features
from flowyml import check_features
check_features()

Requirements by Use Case

Local Development

pip install flowyml

ML Training (TensorFlow)

pip install flowyml[tensorflow]

ML Training (PyTorch)

pip install flowyml[pytorch]

Production on GCP

pip install flowyml[gcp,tensorflow]  # or pytorch

Full Development Setup

pip install flowyml[all,dev]

Installation Best Practices 💡

Use Virtual Environments

Always use virtual environments to avoid dependency conflicts:

# Using venv (built-in)
python -m venv flowyml-env
source flowyml-env/bin/activate  # Windows: flowyml-env\Scripts\activate
pip install "flowyml[all]"

# Using conda
conda create -n flowyml python=3.10
conda activate flowyml
pip install "flowyml[all]"

Why this matters: Prevents conflicts with other Python projects and makes it easy to reproduce your environment.

Pin Versions in Production

For production deployments, pin exact versions:

# Generate requirements file
pip freeze > requirements.txt

# Or use Poetry (recommended)
pip install flowyml[all]
poetry lock

Why this matters: Ensures reproducible deployments and prevents surprise breakages from dependency updates.

Troubleshooting Common Issues

"Module not found" errors for optional features

Problem: You see ImportError or ModuleNotFoundError when using specific features.

Solution: Install the corresponding extra:

# For TensorFlow features
pip install "flowyml[tensorflow]"

# For GCP features
pip install "flowyml[gcp]"

# Or just install everything
pip install "flowyml[all]"

Dependency version conflicts

Problem: pip reports conflicts between FlowyML's dependencies and existing packages.

Solution: Create a fresh virtual environment:

# Deactivate current environment if active
deactivate

# Create new environment
python -m venv new-flowyml-env
source new-flowyml-env/bin/activate
pip install "flowyml[all]"

Python version too old

Problem: Installation fails with Python version errors.

Solution: Upgrade Python to 3.8 or higher:

# Check current version
python --version

# Using conda (recommended)
conda create -n flowyml python=3.10
conda activate flowyml

# Or use pyenv
pyenv install 3.10.0
pyenv local 3.10.0

GCP authentication issues

Problem: Can't access GCS or Vertex AI.

Solution: Authenticate with gcloud:

# Install gcloud CLI first: https://cloud.google.com/sdk/docs/install
gcloud auth login
gcloud auth application-default login
gcloud config set project YOUR-PROJECT-ID

Installation is slow

Problem: pip install takes a very long time.

Solution: Clear pip cache or use a faster mirror:

# Clear cache
pip cache purge

# Or upgrade pip/setuptools
pip install --upgrade pip setuptools wheel

# Then retry
pip install "flowyml[all]"

Next Steps

Once installed:

Verify installation: Run flowyml --version to confirm
Build your first pipeline: Follow the Getting Started guide
Explore examples: Check out the Examples page for real-world patterns

Need help? Visit the Resources page for community support and troubleshooting guides.