deepset-ai--haystack/docs-website/docs/document-stores/faissdocumentstore.mdx

---
title: "FAISSDocumentStore"
id: faissdocumentstore
slug: "/faissdocumentstore"
---

# FAISSDocumentStore

<div className="key-value-table">

|  |  |
| --- | --- |
| API reference | [FAISS](/reference/integrations-faiss)                                                      |
| GitHub link   | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/faiss |

</div>

`FAISSDocumentStore` is a local Document Store backed by [FAISS](https://github.com/facebookresearch/faiss) for vector similarity search.
It keeps vectors in a FAISS index and stores document data in memory, with optional persistence to disk.

`FAISSDocumentStore` is a good fit for local development and small to medium-sized datasets where you want a lightweight setup without running an external database service.

## Installation

Install the FAISS integration:

```shell
pip install faiss-haystack
```

## Initialization

Create a `FAISSDocumentStore` instance and write embedded documents:

```python
from haystack import Document
from haystack.document_stores.types import DuplicatePolicy
from haystack_integrations.document_stores.faiss import FAISSDocumentStore

document_store = FAISSDocumentStore(
    index_path="my_faiss_index",  # Optional: enables persistence on disk
    index_string="Flat",
    embedding_dim=768,
)

document_store.write_documents(
    [
        Document(content="This is first", embedding=[0.1] * 768),
        Document(content="This is second", embedding=[0.2] * 768),
    ],
    policy=DuplicatePolicy.OVERWRITE,
)

print(document_store.count_documents())

# Persist index and metadata files (`.faiss` and `.json`)
document_store.save("my_faiss_index")
```

### Persistence

If you provide `index_path` when initializing `FAISSDocumentStore`, it tries to load existing persisted files (`.faiss` and `.json`) from that path.
You can also explicitly call:

- `save(index_path)` to write index and metadata to disk.
- `load(index_path)` to load them later.

Example of loading from a previously saved folder/path:

```python
from haystack_integrations.document_stores.faiss import FAISSDocumentStore

# This loads `my_faiss_index.faiss` and `my_faiss_index.json` if they exist
document_store = FAISSDocumentStore(index_path="my_faiss_index")

# Alternatively, initialize first and then load explicitly
another_store = FAISSDocumentStore(embedding_dim=768)
another_store.load("my_faiss_index")
```

## Supported Retrievers

[`FAISSEmbeddingRetriever`](../pipeline-components/retrievers/faissembeddingretriever.mdx): Retrieves documents from `FAISSDocumentStore` based on query embeddings.


### Fixing OpenMP Runtime Conflicts on macOS

#### Symptoms

You may encounter one or both of the following errors at runtime:

```
OMP: Error #15: Initializing libomp.dylib, but found libomp.dylib already initialized.
OMP: Hint This means that multiple copies of the OpenMP runtime have been linked into the program.
```

```
resource_tracker: There appear to be 1 leaked semaphore objects to clean up at shutdown
```

If setting `OMP_NUM_THREADS=1` prevents the crash, the root cause is **multiple OpenMP runtimes loaded simultaneously**. Each runtime maintains its own thread pool and thread-local storage (TLS). When two runtimes spin up worker threads at the same time, they corrupt each other's memory — causing segfaults at `N > 1` threads.

---

#### Diagnosis

First, find how many copies of `libomp.dylib` exist in your virtual environment:

```bash
find /path/to/your/.venv -name "libomp.dylib" 2>/dev/null
```

If you see more than one, e.g.:

```
.venv/lib/pythonX.Y/site-packages/torch/lib/libomp.dylib
.venv/lib/pythonX.Y/site-packages/sklearn/.dylibs/libomp.dylib
.venv/lib/pythonX.Y/site-packages/faiss/.dylibs/libomp.dylib
```

you need to consolidate them into a single runtime.

---

#### Fix

The solution is to pick one canonical `libomp.dylib` (torch's is a good choice) and replace all other copies with symlinks pointing to it.

For each duplicate, delete the copy and replace it with a symlink:

```bash
# Delete the duplicate
rm /path/to/.venv/lib/pythonX.Y/site-packages/<package>/.dylibs/libomp.dylib

# Replace with a symlink to the canonical copy
ln -s /path/to/.venv/lib/pythonX.Y/site-packages/torch/lib/libomp.dylib \
      /path/to/.venv/lib/pythonX.Y/site-packages/<package>/.dylibs/libomp.dylib
```

Repeat for every duplicate found. Because these packages use `@loader_path`-relative references to load `libomp.dylib`, the symlink will be transparently resolved to the single canonical runtime at load time.

---

#### Verify

After applying the fix, confirm only one unique `libomp.dylib` is being referenced:

```bash
find /path/to/your/.venv -name "*.so" | xargs otool -L 2>/dev/null | grep libomp | sort -u
```

All entries should resolve to the same canonical path. You should now be able to run without `OMP_NUM_THREADS=1`.