# 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?](fl_introduction.md#fl-introduction) and have reviewed the [NVIDIA FLARE Overview](flare_overview.md#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](user_guide/admin_guide/deployment/containerized_deployment.md#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](https://docs.python.org/3/library/venv.html). 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. ```shell $ sudo apt update $ sudo apt-get install python3-venv ``` Once venv is installed, you can use it to create a virtual environment with: ```shell $ 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: ```shell $ source nvflare-env/bin/activate ``` You may find that the pip and setuptools versions in the venv need updating: ```shell (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](https://pypi.org/project/nvflare): ```shell $ 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: ```shell $ 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: ```shell $ 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: ```shell $ pip install nvflare[PT] ``` * **SKLEARN** - Scikit-learn support: ```shell $ pip install nvflare[SKLEARN] ``` * **TRACKING** - MLflow, Weights & Biases, and TensorBoard support: ```shell $ pip install nvflare[TRACKING] ``` * **MONITORING** - Datadog monitoring support: ```shell $ pip install nvflare[MONITORING] ``` * **DASHBOARD** - Dashboard web interface: ```shell $ python3 -m pip install "nvflare[dashboard]" ``` You can also install multiple optional dependencies at once: ```shell $ 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): ```shell # 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): ```shell $ 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: ```shell $ pip install -e ".[dev]" # Install all development dependencies $ pip install -e ".[PT,SKLEARN]" # Install specific optional dependencies ``` Note on branches: * The [main](https://github.com/NVIDIA/NVFlare/tree/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: ```shell $ 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: ```shell $ python -m pip install build ``` 1. Build the wheel: ```shell $ python -m build --wheel ``` This creates `dist/nvflare--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): ```shell $ python -m pip install "dist/nvflare--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: ```shell $ python -m pip install "dist/nvflare--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: ```shell $ 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: ```shell $ 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](quickstart.md#quickstart) guide to run your first federated learning example 2. Learn more about different ways to use NVFlare in the [Quick Start](quickstart.md#getting-started) guide 3. Explore more examples in the [Example Applications](example_applications_algorithms.md#example-applications) section 4. When ready for production, see [Deployment Overview](user_guide/admin_guide/deployment/overview.md#deployment-overview) for deployment guidance