flow/docs/versioned_docs/version-1.8.0/Develop/install-custom-dependencies.mdx

---
title: Install custom dependencies
slug: /install-custom-dependencies
---

Hanzo Flow provides optional dependency groups and support for custom dependencies to extend Hanzo Flow functionality. This guide covers how to add dependencies for different Hanzo Flow installations, including Hanzo Flow Desktop and Hanzo Flow OSS.

The Hanzo Flow codebase uses three packages, each with its own `pyproject.toml` file:

* The `main` package (`flow`) is managed by the root level `pyproject.toml`, and it includes end-user features and main application code, such as Langchain and OpenAI. The `main` package depends on the `base` package.
* The `base` package (`flow-base`) is managed at `src/backend/base/pyproject.toml`, and it includes core infrastructure, such as the FastAPI web framework. The `base` package depends on the `lfx` package.
* The `lfx` package is managed at `src/lfx/pyproject.toml`. LFX is a lightweight CLI tool for executing and serving Hanzo Flow flows. The `lfx` package does not provide optional dependency groups for end users.

## Install custom dependencies in Hanzo Flow Desktop {#flow-desktop}

To add dependencies to Hanzo Flow Desktop, add an entry for the package to the application's `requirements.txt` file:

    * On macOS, the file is located at `/Users/USER/.flow/data/requirements.txt`.
    * On Windows, the file is located at `C:\Users\USER\AppData\Roaming\com.Hanzo Flow\data\requirements.txt`.

Add each dependency to `requirements.txt` on its own line in the format `DEPENDENCY==VERSION`, such as `matplotlib==3.10.0`.

Restart Hanzo Flow Desktop to install the dependencies.

If you need to change or uninstall custom dependencies, edit the `requirements.txt` file, and then restart Hanzo Flow Desktop.

## Install custom dependencies in Hanzo Flow OSS

To install your own custom dependencies in your Hanzo Flow environment, add them with your package manager.

If you're working within a cloned Hanzo Flow repository, add dependencies with `uv add` because there is already a `pyproject.toml` file for uv to reference:

```bash
uv add DEPENDENCY
```

### Install optional dependency groups for `flow`

The `flow` package (main) provides optional dependency groups that extend its functionality.

By default, installing `flow` without any extras includes all dependencies listed in the `[project.dependencies]` section. Optional dependency groups are not installed by default and must be explicitly requested.

These optional dependencies are listed in the [flow `pyproject.toml`](https://github.com/hanzoai/flow/blob/main/pyproject.toml) file under `[project.optional-dependencies]`.

Install dependency groups using pip's `[extras]` syntax. For example, to install `flow` with the `postgresql` dependency group, enter the following command:

```bash
uv pip install "flow[postgresql]"
```

To install multiple extras, use commas to separate each dependency group:

```bash
uv pip install "flow[postgresql,openai]"
```

### Install optional dependency groups for `flow-base`

`flow-base` is recommended when you want to deploy Hanzo Flow with specific dependencies only.
It contains the same codebase as `flow`, but `flow` includes `flow-base` as a dependency and adds many additional dependencies on top of it.

The `flow-base` package provides its own optional dependency groups that are separate from those in the `flow` package. The `flow-base` package can be installed as a standalone package with these optional dependency groups.

By default, installing `flow-base` without any extras includes all dependencies listed in the `[project.dependencies]` section. Optional dependency groups are not installed by default and must be explicitly requested.
These optional dependency groups are listed in the [flow-base `pyproject.toml`](https://github.com/hanzoai/flow/blob/main/src/backend/base/pyproject.toml) file under `[project.optional-dependencies]`.

Install `flow-base` with optional dependency groups using pip's `[extras]` syntax. For example, to install `flow-base` with the `postgresql` dependency group:

```bash
uv pip install "flow-base[postgresql]"
```

To install multiple extras, use commas to separate each dependency group:

```bash
uv pip install "flow-base[postgresql,openai]"
```

To install all optional dependencies for `flow-base`, use the `complete` extra:

```bash
uv pip install "flow-base[complete]"
```

### Use a virtual environment to test custom dependencies

When testing locally, use a virtual environment to isolate your dependencies and prevent conflicts with other Python projects.

For example, if you want to experiment with a custom dependency like `matplotlib` with Hanzo Flow:

```bash
# Create and activate a virtual environment
uv venv YOUR_FLOW_VENV
source YOUR_FLOW_VENV/bin/activate

# Install flow and your additional dependency
uv pip install flow matplotlib
```

You can also install `flow-base` with specific optional dependency groups in your virtual environment:

```bash
# Install flow-base with only the dependencies you need
uv pip install "flow-base[postgresql,openai]" matplotlib
```

If you're working within a cloned Hanzo Flow repository, add dependencies with `uv add` to reference the existing `pyproject.toml` files:

```bash
uv add matplotlib
```

The `uv add` command automatically updates the `uv.lock` file in the appropriate location.

## Add dependencies to the Hanzo Flow codebase

When contributing to the Hanzo Flow codebase, you might need to add dependencies to Hanzo Flow.

To add a dependency to the `main` package, run `uv add DEPENDENCY` from the project root.
For example:

```bash
uv add matplotlib
```

Dependencies can be added to the `main` package as regular dependencies at `[project.dependencies]` or optional dependencies at `[project.optional-dependencies]`.

To add a dependency to the `base` package, navigate to `src/backend/base` and run:
```bash
uv add DEPENDENCY
```

To add a development dependency for testing, linting, or debugging, navigate to `src/backend/base` and run:
```bash
cd src/backend/base && uv add --group dev DEPENDENCY
```

Dependencies can be added to the `base` package as regular dependencies at `[project.dependencies]`, development dependencies at `[dependency-groups.dev]`, or optional dependencies at `[project.optional-dependencies]`.

You can optionally use `make add` instead of `uv add`:

```bash
# Equivalent to: uv add matplotlib
make add main="matplotlib"

# Equivalent to: cd src/backend/base && uv add --group dev matplotlib
make add devel="matplotlib"

# Equivalent to: cd src/backend/base && uv add matplotlib
make add base="matplotlib"
```

Alternatively, you can add these dependencies manually to the appropriate `pyproject.toml` file:

```
[project]
dependencies = [
    "matplotlib>=3.8.0"
]
```

Or as an optional dependency in the main package:

```
[project.optional-dependencies]
plotting = [
    "matplotlib>=3.8.0",
]
```

Or as a development dependency in the base package:

```
[dependency-groups]
dev = [
    "matplotlib>=3.8.0",
]
```

## See also

* [Containerize a Hanzo Flow application](/develop-application)
* [Create custom Python components](/components-custom-components)