Install & Compatibility
Where this runs
tested against v1.30.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.940 runs
installs and imports cleanly · install 0.0s · import 3.719s · 190.3MB
glibcpy 3.10–3.940 runs
installs and imports cleanly · install 11.8s · import 3.018s · 183MB
187MB installed
● package 187MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
start_server
✓ from flwr.server import start_server
start_client
✓ from flwr.client import start_client
start_simulation
✓ from flwr.simulation import start_simulation
Used for running federated learning simulations locally without needing separate client processes.
Client
✓ from flwr.client import Client
NumPyClient
✓ from flwr.client import NumPyClient
A convenient base class for clients that exchange NumPy arrays, simplifying client implementation.
Strategy
✓ from flwr.server.strategy import Strategy
Base class for implementing custom federated learning strategies.
FedAvg
✓ from flwr.server.strategy import FedAvg
The most commonly used federated averaging strategy, provided out-of-the-box.
Message
✓ from flwr.common import Message
✗ from flwr.common import NDArrays
Flower migrated from `NDArrays` (NumPy array list) to a more flexible `Message` API starting from v1.21.0. While `NDArrays` still exists for backward compatibility, `Message` is the recommended and future-proof way to exchange data and configure steps.
This quickstart demonstrates how to set up a basic federated learning simulation using Flower. It defines a `NumPyClient` subclass with dummy model logic for parameter exchange, training, and evaluation. It then configures a `FedAvg` strategy and launches a local simulation using `flwr.simulation.start_simulation`, which manages multiple clients and the server within a single process for easy testing.
import flwr as fw
import numpy as np
from collections import OrderedDict
# 1. Define a Flower Client (inheriting from NumPyClient)
class CifarClient(fw.client.NumPyClient):
def __init__(self):
# In a real scenario, you'd load your actual ML model here
# For this quickstart, we'll use a dummy model with NumPy arrays.
self.model = {
"layer1": np.random.rand(10, 10).astype(np.float32),
"layer2": np.random.rand(10, 1).astype(np.float32)
}
def get_parameters(self, config):
"""Return model parameters as a list of NumPy arrays."""
return [v for v in self.model.values()]
def set_parameters(self, parameters):
"""Set model parameters from a list of NumPy arrays."""
params_dict = zip(self.model.keys(), parameters)
self.model = OrderedDict({k: v for k, v in params_dict})
def fit(self, parameters, config):
"""Simulate training and return updated parameters, number of examples, and metrics."""
self.set_parameters(parameters)
# Simulate training: update weights slightly
new_weights = {k: v + np.random.rand(*v.shape).astype(np.float32) * 0.1 for k, v in self.model.items()}
self.model = OrderedDict(new_weights)
num_examples = 100
metrics = {"accuracy": float(np.random.rand())}
return self.get_parameters({}), num_examples, metrics
def evaluate(self, parameters, config):
"""Simulate evaluation and return loss, number of examples, and metrics."""
self.set_parameters(parameters)
# Simulate evaluation
loss = float(np.random.rand() * 0.5 + 0.5) # Loss between 0.5 and 1.0
accuracy = float(np.random.rand() * 0.2 + 0.7) # Accuracy between 0.7 and 0.9
num_examples = 50
return loss, num_examples, {"accuracy": accuracy}
# 2. Define a Flower Server Strategy
# FedAvg (Federated Averaging) is a common choice.
strategy = fw.server.strategy.FedAvg(
fraction_fit=1.0, # Sample 100% of available clients for training
fraction_evaluate=1.0, # Sample 100% of available clients for evaluation
min_fit_clients=2, # Wait for at least 2 clients to participate in fit
min_evaluate_clients=2, # Wait for at least 2 clients to participate in evaluate
min_available_clients=2, # Total number of clients that need to be connected
)
# 3. Define the client factory function for the simulation
def client_fn(cid: str):
"""Returns a Flower Client for a given client ID."""
print(f"Creating client {cid}...")
return CifarClient().to_client()
# 4. Start the Flower Simulation
print("Starting Flower simulation with 2 clients for 3 rounds...")
fw.simulation.start_simulation(
client_fn=client_fn,
num_clients=2,
config=fw.server.ServerConfig(num_rounds=3),
strategy=strategy,
)
print("Simulation finished.")
flwr --version
Debug
Known issues
breakingFlower has migrated its internal communication and strategy APIs from using raw `NDArrays` (lists of NumPy arrays) to a more flexible `Message` API. Older code that directly manipulated `NDArrays` for parameter exchange or implemented custom strategies without the `Message` API will need significant updates.fixReview the official documentation on `flwr.common.Message` and the updated `flwr.server.strategy.Strategy` interface. Client implementations should primarily use `NumPyClient` (which handles `Message` conversion internally) or directly work with `Message` objects. Custom strategies must implement methods compatible with the new Message API.
affects: >=1.21.0, >=1.22.0
gotchaFlower's base installation (`pip install flwr`) does not include machine learning framework dependencies. If you intend to use PyTorch, TensorFlow, or JAX, you must install Flower with the appropriate optional dependencies, otherwise you will encounter `ModuleNotFoundError`.fixInstall Flower with the relevant extras, e.g., `pip install 'flwr[torch]'`, `pip install 'flwr[tensorflow]'`, or `pip install 'flwr[jax]'`. Ensure that the versions of the ML framework packages are compatible with your `flwr` version and Python environment.
affects: All versions
gotchaFlower requires Python version `>=3.10` and `<4.0`. Using an incompatible Python interpreter (e.g., Python 3.9 or Python 4.0+) will lead to installation failures, runtime errors, or unexpected behavior.fixAlways use a virtual environment and ensure it's configured with a Python version within the `flwr`'s supported range. For example, `conda create -n flwr_env python=3.10` or `pyenv install 3.11.x` followed by `pyenv local 3.11.x`.
affects: All versions
breakingThe `flwr` CLI has undergone several changes, including the introduction of centralized configuration via a `pyproject.toml` or `flwr.json` file. Old command-line arguments and script patterns for starting servers or simulations might no longer work as expected.fixConsult the latest `flwr` documentation for current CLI usage, configuration options, and examples for launching servers and simulations. Update any legacy scripts that rely on older CLI syntax or configuration file formats.
affects: >=1.26.0
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'flower'
The Python package name for Flower is `flwr`, not `flower`.
fixChange your import statements from `import flower` to `import flwr` and ensure you installed it using `pip install flwr`.
AttributeError: 'Client' object has no attribute 'get_parameters' (or 'fit', 'evaluate', etc.)
You are attempting to use methods of a `flwr.client.Client` object (or a custom client) that are either not implemented, misspelled, or do not conform to the expected API for parameter exchange and federated operations.
fixFor common use cases, subclass `flwr.client.NumPyClient` and override its methods (`get_parameters`, `set_parameters`, `fit`, `evaluate`). If implementing a custom client directly from `flwr.client.Client`, ensure all abstract methods are correctly implemented according to the latest API.
ValueError: incompatible buffer format, expected 'float32', got 'float64'
A mismatch in the data types of NumPy arrays (e.g., `float32` vs `float64`) being exchanged between clients and the server, often due to how different ML frameworks (PyTorch, TensorFlow) handle default data types.
fixExplicitly cast all NumPy arrays to the required `dtype` (e.g., `np.float32`) before returning them from client methods like `get_parameters`, `fit`, or `evaluate`. For example: `[v.astype(np.float32) for v in self.model.values()]`.
grpc._channel._MultiThreadedRendezvous: <_MultiThreadedRendezvous of RPC that terminated with status StatusCode.UNAVAILABLE (or similar connection errors)>
The client failed to connect to the Flower server. This could be due to the server not running, an incorrect server address/port, network issues, or a firewall blocking the connection.
fixVerify that the Flower server is running and listening on the specified `server_address` (e.g., `127.0.0.1:8080`). Check network connectivity, ensure no firewall is blocking the port, and confirm the port is not already in use by another application. For local testing, ensure the client and server use the exact same address and port.
ImportError: cannot import name 'xyz' from 'flwr.common'
Attempting to import a symbol (e.g., `NDArrays`, `Parameters`) that has been removed or deprecated in favor of the new `Message` API, or has been moved to a different module.
fixConsult the `flwr` documentation for the latest API. For parameter exchange, use `flwr.common.Message` or rely on `NumPyClient` which abstracts this. If a symbol was moved, search the documentation or `flwr` source code for its new location.
Upgrade
Version history
1.31.0latest on PyPI · released Jun 8, 2026
Audit
Dependencies
torchoptionalRequired for PyTorch-based federated learning applications.
tensorflowoptionalRequired for TensorFlow-based federated learning applications.
jaxoptionalRequired for JAX-based federated learning applications.
protobufrequiredUsed for data serialization and RPC communication. Typically installed as a core dependency.
grpciorequiredUsed for gRPC communication between clients and server. Typically installed as a core dependency.