fluke: federated learning utility framework for experimentation and research

fluke is a Python package that provides a framework for federated learning research. It is designed to be modular and extensible, allowing researchers to easily implement and test new federated learning algorithms. fluke provides a set of pre-implemented state-of-the-art federated learning algorithms that can be used as a starting point for research or as a benchmark for comparison.

Installation

Pypi

fluke is a Python package that can be installed via pip. To install it, you can run the following command:

pip install fluke-fl

Clone the repository

You can also install fluke by cloning the repository and installing it in editable mode. This is useful if you want to contribute to the development of fluke or if you want to use the latest version of the code.

git clone https://github.com/makgyver/fluke.git
cd fluke
pip install -e .

[!WARNING] Due to a recent repository tree refactoring, if you cloned the repository before June 2025, you need to reclone it to get the latest version of the code.

🐳 Docker

You can use this library directly inside a Docker container — no installation needed on your local machine.

docker build -t fluke_container .

Then, you can run an interactive session with

docker run --rm fluke_container fluke [ARGS]

where ARGS are the arguments you want to pass to the fluke command as described in the next section.

Run a federated algorithm

To run an algorithm in fluke you need to create two configuration files:

• EXP_CONFIG: the experiment configuration file (independent from the algorithm);
• ALG_CONFIG: the algorithm configuration file;

Then, you can run the following command:

fluke federation EXP_CONFIG ALG_CONFIG

You can find some examples of these files in the configs folder of the repository.

Example

Let say you want to run the classic FedAvg algorithm on the MNIST dataset. Then, using the configuration files exp.yaml and fedavg.yaml, you can run the following command:

fluke federation path_to_folder/exp.yaml path_to_folder/fedavg.yaml

where path_to_folder is the path to the folder containing the configuration files.

Documentation

The documentation for fluke can be found here. It contains detailed information about the package, including how to install it, how to run an experiment, and how to implement new algorithms.

Tutorials

Tutorials on how to use fluke can be found here. In the following, you can find some quick tutorials to get started with fluke:

• Getting started with fluke API
• Run your algorithm in fluke
• Use your own model with fluke
• Add your dataset and use it with fluke
• Add your custom evaluation metric in fluke

Contributing

If you have suggestions for how fluke could be improved, or want to report a bug, open an issue! We'd love all and any contributions.

For more, check out the Contributing Guide.

fluke @ ECML-PKDD 2024

fluke has been presented at the ECML-PKDD 2024 conference in the Workshop on Advancements in Federated Learning. The slides of the presentation are available here.

fluke @ ECAI 2025

On 25th October, we will deliver a tutorial on fluke at the 28th European Conference on Artificial Intelligence (ECAI). Here the website of the tutorial.

Citing fluke

fluke is a research tool, and we kindly ask you to cite it in your research papers if you use it. You can use the following BibTeX entry:

@article{fluke2025fgcs,
	title = {Fluke: Federated learning utility framework for experimentation and research},
	journal = {Future Generation Computer Systems},
	volume = {177},
	pages = {108241},
	year = {2026},
	issn = {0167-739X},
	doi = {https://doi.org/10.1016/j.future.2025.108241},
	url = {https://www.sciencedirect.com/science/article/pii/S0167739X25005357},
	author = {Mirko Polato}
}

Authors and main contributors

• Mirko Polato - Idealization, Design, Development, Testing, Tutorial, and Documentation
• Roberto Esposito - Testing
• Samuele Fonio - Testing, Tutorial
• Edoardo Oglietti - Testing