https://github.com/makgyver/fluke
Federated learning framework made by researchers for researchers :)
https://github.com/makgyver/fluke
federated-learning machine-learning-library pypi-packages
Last synced: 2 months ago
JSON representation
Federated learning framework made by researchers for researchers :)
- Host: GitHub
- URL: https://github.com/makgyver/fluke
- Owner: makgyver
- License: lgpl-2.1
- Created: 2022-12-09T08:46:32.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2026-03-10T08:09:32.000Z (2 months ago)
- Last Synced: 2026-03-10T12:45:39.963Z (2 months ago)
- Topics: federated-learning, machine-learning-library, pypi-packages
- Language: Python
- Homepage: https://makgyver.github.io/fluke/
- Size: 6.52 MB
- Stars: 52
- Watchers: 4
- Forks: 11
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
[](https://www.sciencedirect.com/science/article/pii/S0167739X25005357)
# **fluke**: **f**ederated **l**earning **u**tility framewor**k** for **e**xperimentation 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:
```bash
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.
```bash
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.
```bash
docker build -t fluke_container .
```
Then, you can run an interactive session with
```bash
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:
```bash
fluke federation EXP_CONFIG ALG_CONFIG
```
You can find some examples of these files in the [configs](https://github.com/makgyver/fluke/tree/main/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](https://github.com/makgyver/fluke/blob/main/configs/exp.yaml) and [fedavg.yaml](https://github.com/makgyver/fluke/blob/main/configs/fedavg.yaml), you can run the following command:
```bash
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](https://makgyver.github.io/fluke). 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](https://makgyver.github.io/fluke/tutorials.html). In the following, you can find some quick tutorials to get started with ``fluke``:
- Getting started with `fluke` API [
](https://colab.research.google.com/github/makgyver/fluke/blob/main/tutorials/fluke_quick_api.ipynb)
- Run your algorithm in ``fluke`` [
](https://colab.research.google.com/github/makgyver/fluke/blob/main/tutorials/fluke_custom_alg.ipynb)
- Use your own model with `fluke` [
](https://colab.research.google.com/github/makgyver/fluke/blob/main/tutorials/fluke_custom_nn.ipynb)
- Add your dataset and use it with ``fluke`` [
](https://colab.research.google.com/github/makgyver/fluke/blob/main/tutorials/fluke_custom_dataset.ipynb)
- Add your custom evaluation metric in ``fluke`` [
](https://colab.research.google.com/github/makgyver/fluke/blob/main/tutorials/fluke_custom_eval.ipynb)
## 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](CONTRIBUTING.md).
## `fluke` @ ECML-PKDD 2024
`fluke` has been presented at the [ECML-PKDD 2024](https://ecmlpkdd2024.org/) conference in the [Workshop on Advancements in Federated Learning](https://wafl2024.di.unito.it). The slides of the presentation are available [here](slides/fluke_ecmlpkdd2024.pdf).
## `fluke` @ ECAI 2025
On 25th October, we will deliver a tutorial on `fluke` at the 28th European Conference on Artificial Intelligence (ECAI). [Here](https://sites.google.com/view/fluketutorialecai25/home) 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:
```bibtex
@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**](https://makgyver.github.io) - *Idealization*, *Design*, *Development*, *Testing*, *Tutorial*, and *Documentation*
- [**Roberto Esposito**](https://github.com/boborbt) - *Testing*
- [**Samuele Fonio**](https://github.com/samuelefonio) - *Testing*, *Tutorial*
- [**Edoardo Oglietti**](https://github.com/00-uno-00) - *Testing*