Persistence and I/O#

Annoy’s native strength is a compact index that can be memory-mapped after it is built. The high-level facade adds several persistence choices; use the least powerful one that matches your requirement.

Native index files#

Use save_index / load_index (or the corresponding low-level save / load methods) when you only need the Annoy index artifact. This is the most direct representation and is appropriate for process-shared, read-mostly retrieval.

Bundles and metadata#

The I/O and metadata mixins can publish a bundle containing the index plus versioned metadata. Prefer this when an index must travel with enough parameters to validate how it should be reconstructed.

Byte serialization and pickle#

Byte serialization is useful for controlled application transport. Pickle is a Python object persistence mechanism and must be treated as executable input: never unpickle data from an untrusted source. Compression modes affect storage size, not the trust boundary.

Mmap lifetime#

Loading may memory-map index data. Keep the underlying artifact available for as long as the mapped index is in use. Replacing or truncating a mapped file in place is not a safe publication strategy; publish a new artifact and switch readers to it.