Installation

This guide covers the installation of NVIDIA FLARE and its dependencies. Before proceeding, make sure you understand the basics of federated learning from the What is Federated Learning? and have reviewed the NVIDIA FLARE Overview to understand what you’ll be installing.

Prerequisites

  • Python 3.10+ (tested through Python 3.14, including Python 3.13)

  • pip

  • Git

Note

The server and client versions of nvflare must match, we do not support cross-version compatibility.

Supported Operating Systems

  • Linux

  • OSX (Note: some optional dependencies are not compatible, such as tenseal and openmined.psi)

Installation Methods

Virtual Environment Setup

It is highly recommended to install NVIDIA FLARE in a virtual environment if you are not using Containerized Deployment. This guide briefly describes how to create a virtual environment with venv.

Virtual Environments and Packages

Python’s official document explains the main idea about virtual environments. The module used to create and manage virtual environments is called venv. You can find more information there. We only describe a few necessary steps for a virtual environment for NVIDIA FLARE.

Depending on your OS and the Python distribution, you may need to install the Python’s venv package separately. For example, in Ubuntu 20.04, you need to run the following commands to continue creating a virtual environment with venv.

$ sudo apt update
$ sudo apt-get install python3-venv

Once venv is installed, you can use it to create a virtual environment with:

$ python3 -m venv nvflare-env

This will create the nvflare-env directory in current working directory if it doesn’t exist, and also create directories inside it containing a copy of the Python interpreter, the standard library, and various supporting files.

Activate the virtualenv by running the following command:

$ source nvflare-env/bin/activate

You may find that the pip and setuptools versions in the venv need updating:

(nvflare-env) $ python3 -m pip install -U pip
(nvflare-env) $ python3 -m pip install -U setuptools

Install Stable Release

Stable releases are available on NVIDIA FLARE PyPI:

$ python3 -m pip install nvflare

Optional Dependencies

NVFlare provides several optional dependency groups that you can install based on your needs:

  • HE - Homomorphic Encryption support:

    $ pip install nvflare[HE]

    Note

    nvflare[HE] currently supports Python 3.10-3.13. On Python 3.14, tenseal is not available yet, so the HE extra is not installed.

  • PSI - Private Set Intersection support:

    $ pip install nvflare[PSI]

    Note

    nvflare[PSI] currently supports Python 3.10-3.13. On Python 3.14, openmined.psi is not available yet, so the PSI extra is not installed.

  • PT - PyTorch support:

    $ pip install nvflare[PT]

  • SKLEARN - Scikit-learn support:

    $ pip install nvflare[SKLEARN]

  • TRACKING - MLflow, Weights & Biases, and TensorBoard support:

    $ pip install nvflare[TRACKING]

  • MONITORING - Datadog monitoring support:

    $ pip install nvflare[MONITORING]

  • DASHBOARD - Dashboard web interface:

    $ python3 -m pip install "nvflare[dashboard]"

You can also install multiple optional dependencies at once:

$ pip install nvflare[PT,SKLEARN,TRACKING]  # Install PyTorch, Scikit-learn, and tracking support

For development, you can install all dependencies (except HE and PSI on macOS):

# On Linux
$ pip install nvflare[dev]

# On macOS
$ pip install nvflare[dev_mac]

Install from Source

Clone NVFlare repo and install from source (useful for accessing unreleased features or testing custom builds):

$ git clone https://github.com/NVIDIA/NVFlare.git
$ cd NVFlare
$ pip install -e .  # Install in editable mode

You can also install with optional dependencies from source:

$ pip install -e ".[dev]"  # Install all development dependencies
$ pip install -e ".[PT,SKLEARN]"  # Install specific optional dependencies

Note on branches:

  • The main branch is the default (unstable) development branch

  • The 2.1, 2.2, 2.3, 2.4, 2.5, 2.6, 2.7 etc. branches are the branches for each major release and there are tags based on these with a third digit for minor patches

To switch to a specific branch:

$ git switch 2.7  # Replace with desired version

Building Wheels

You can build wheel packages for NVFlare using the following steps:

  1. Install build dependencies:

$ python -m pip install build

  1. Build the wheel:

$ python -m build --wheel

This creates dist/nvflare-<version>-py3-none-any.whl. Release builds, local development wheels, and editable installs all use the distribution name nvflare. Versioneer derives the version and source revision from the checkout; NVFL_RELEASE no longer changes the NVFlare package name. This applies to the main package built by the repository-root setup.py. The separate nvflight/setup.py packaging still uses NVFL_RELEASE to choose between nvflare-light and nvflare-light-nightly. This does not introduce a nightly publishing service. For unreleased features, install from source or build a local wheel.

Install the wheel you built with pip, for example (replace the filename with the actual wheel path):

$ python -m pip install "dist/nvflare-<version>-py3-none-any.whl"

To add optional dependencies to a local wheel installation, use that same wheel with the desired extras. This avoids asking an index for a local build that has never been published:

$ python -m pip install "dist/nvflare-<version>-py3-none-any.whl[PT]"

For an editable install, run python -m pip install -e ".[PT]" from the same checkout instead. Keep the checkout unchanged when using nvflare examples get so the catalog can select its matching revision.

Migrating an existing nvflare-nightly installation

Older source builds used the distribution name nvflare-nightly. That name is retired for new builds; public nightly publishing is not being resumed. Pip treats the two names as separate distributions even though both install nvflare modules, so installing the new package does not remove the old one.

Use a new virtual environment, or remove both distributions before reinstalling the desired wheel or source checkout. Removing both first also repairs an environment where the distributions shared files:

$ python -m pip uninstall nvflare-nightly nvflare
$ python -m pip install -e ".[PT]"  # Run from the desired NVFlare checkout

Build scripts should look for nvflare-*.whl rather than nvflare_nightly-*.whl. Dependencies on nvflare-nightly must be changed to nvflare with an appropriate version constraint. A development version still needs to satisfy that constraint; using one name does not make an incompatible version acceptable to pip.

Running the Build with a Specific Python Version

Run the build module with the desired Python interpreter:

$ python3.14 -m pip install build
$ python3.14 -m build --wheel

Note

With the default build configuration, the wheel is tagged py3-none-any. The build does not use PYTHON or PLATFORM environment variables to select the interpreter or platform tag.

Next Steps

After completing the installation:

  1. Follow the Quick Start guide to run your first federated learning example

  2. Learn more about different ways to use NVFlare in the Quick Start guide

  3. Explore more examples in the Example Applications section

  4. When ready for production, see Deployment Overview for deployment guidance