Install & Compatibility
Where this runs
tested against v9.12.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Embeddings (basic semantic search)
✓ from txtai import Embeddings
# Default model (all-MiniLM-L6-v2)
embeddings = Embeddings()
# Or specify model explicitly
embeddings = Embeddings(path='sentence-transformers/all-MiniLM-L6-v2')
# index() — builds NEW index, overwrites existing
embeddings.index(['Correct answer', 'Wrong answer', 'Maybe'])
# search returns list of (id, score) tuples
results = embeddings.search('positive', 1)
print(results) # [(0, 0.298)] — id=0 is 'Correct answer'
✗ from txtai import Embeddings
embeddings = Embeddings()
embeddings.index(['doc 1', 'doc 2'])
# Wrong: index() again REPLACES the entire index
embeddings.index(['doc 3']) # doc 1 and doc 2 are now gone
# Wrong: expecting text back from search without content storage
text = embeddings.search('query', 1)[0][0] # returns id (int), not text
index() rebuilds the entire index from scratch — calling it again wipes previous data. Use upsert() to add/update without full rebuild. search() returns (id, score) tuples by default, not text.
Embeddings with content storage
✓ from txtai import Embeddings
# Enable content storage to retrieve text from search results
embeddings = Embeddings(content=True)
# Index with dict documents
embeddings.index([
{'id': 0, 'text': 'Python is a programming language'},
{'id': 1, 'text': 'JavaScript runs in browsers'},
{'id': 2, 'text': 'Rust is fast and safe'},
])
# Now search returns dicts with text
results = embeddings.search('compiled language', 1)
print(results[0]['text']) # 'Rust is fast and safe'
# Can also use SQL
results = embeddings.search(
"SELECT text, score FROM txtai WHERE similar('web language') LIMIT 1"
)
✗ # Without content=True, search only returns (id, score)
embeddings = Embeddings()
embeddings.index(['text 1', 'text 2'])
results = embeddings.search('query', 1)
print(results[0]['text']) # KeyError — no text in result
Without content=True, search returns (id, score) tuples only. Enable content=True to store and retrieve document text. SQL queries also require content=True.
txtai Embeddings with content storage, search, upsert, save/load.
# pip install txtai
from txtai import Embeddings
# Create embeddings with content storage
embeddings = Embeddings(
path='sentence-transformers/all-MiniLM-L6-v2',
content=True
)
# Index documents
embeddings.index([
{'id': 0, 'text': 'Python is a programming language created by Guido'},
{'id': 1, 'text': 'JavaScript is used for web development'},
{'id': 2, 'text': 'Rust provides memory safety without garbage collection'},
{'id': 3, 'text': 'Go is designed for cloud infrastructure'},
])
# Semantic search — returns dicts with text
results = embeddings.search('systems programming language', 2)
for r in results:
print(r['text'], r['score'])
# Upsert — add without rebuilding
embeddings.upsert([{'id': 4, 'text': 'TypeScript adds types to JavaScript'}])
# Save and load
embeddings.save('/tmp/myindex')
embeddings.load('/tmp/myindex')
txtai --version
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'txtai'
The `txtai` library has not been installed in the current Python environment or the environment is not active.
ValueError: content must be enabled to save content
The `Embeddings` index was initialized without enabling content storage, preventing content retrieval or SQL queries.
fixInitialize `Embeddings` with `content=True`, e.g., `Embeddings(config={'content': True})`. OSError: Can't load tokenizer for 'sentence-transformers/all-MiniLM-L6-v2'. If you were trying to load it from 'https://huggingface.co/sentence-transformers/all-MiniLM-L6-v2', make sure you don't have a local directory with the same name.
The specified `sentence-transformers` model cannot be loaded, possibly due to a network issue, a typo in the model name, insufficient disk space, or a corrupted local cache.
fixVerify the model name and internet connectivity, ensure sufficient disk space, or clear the Hugging Face cache (usually `~/.cache/huggingface/hub`) if a corrupted download is suspected.
AttributeError: 'txtai.embeddings.Embeddings' object has no attribute 'add'
The `Embeddings` object in `txtai` does not have an `add` method; data is added using `index` or `upsert`.
fixUse `embeddings.index(data)` to rebuild the index or `embeddings.upsert(data)` to add/update existing data.
TypeError: 'str' object is not iterable
The `embeddings.index()` or `embeddings.upsert()` method expects the `data` argument to be a list of items, but a single string (or other non-iterable object) was provided.
fixWrap the input data in a list, even if it's a single item, e.g., `embeddings.index(["text_item"])` or `embeddings.upsert([("id1", "text_item", None)])`. Upgrade
Version history
9.12.0latest on PyPI · released Jul 30, 2026
Audit
Dependencies
torchoptionalRequired for local model inference. Not installed by default — install separately or via txtai[model].
sentence-transformersoptionalRequired for sentence embedding models. Install via txtai[similarity].
faiss-cpurequiredDefault ANN backend. Installed automatically with txtai.