{"id":9968,"library":"nano-vectordb","title":"Nano VectorDB","description":"Nano VectorDB is a simple, easy-to-hack, in-memory, disk-persisted vector database implementation. It's designed for rapid prototyping, educational purposes, and small-scale applications, offering a lightweight alternative to more complex solutions. The current version is 0.0.4.3, with an active development cadence featuring frequent minor releases.","status":"active","version":"0.0.4.3","language":"en","source_language":"en","source_url":"https://github.com/gusye1234/nano-vectordb","tags":["vector database","embeddings","AI","search","lightweight","in-memory","prototyping"],"install":[{"cmd":"pip install nano-vectordb","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Essential for handling vector (embedding) data.","package":"numpy","optional":false},{"reason":"Used internally for similarity calculations or related utilities.","package":"scikit-learn","optional":false},{"reason":"Provides progress bars for operations, enhancing user experience.","package":"tqdm","optional":false}],"imports":[{"note":"The primary class is exposed directly at the top level of the package, not in a submodule.","wrong":"from nano_vectordb.core import NanoVectorDB","symbol":"NanoVectorDB","correct":"from nano_vectordb import NanoVectorDB"}],"quickstart":{"code":"import numpy as np\nfrom nano_vectordb import NanoVectorDB\nimport os\nimport shutil\n\n# Initialize the database\ndb_path = \"my_nano_vectordb\"\ndb = NanoVectorDB(db_path, dim=4)\n\n# Add vectors with metadata and IDs\ndb.add(np.array([1.0, 2.0, 3.0, 4.0]), {\"text\": \"The quick brown fox.\"}, \"doc1\")\ndb.add(np.array([1.1, 2.1, 3.1, 4.1]), {\"text\": \"Jumps over the lazy dog.\"}, \"doc2\")\ndb.add(np.array([0.9, 1.9, 2.9, 3.9]), {\"text\": \"Another relevant document.\"}, \"doc3\")\n\n# Perform a similarity search\nquery_vector = np.array([1.0, 2.0, 3.0, 4.0])\nk_results = 2\nresults = db.search(query_vector, k=k_results)\n\nprint(f\"\\nSearch Results for top {k_results} documents:\")\nfor vector, metadata, vector_id, score in results:\n    print(f\"  ID: {vector_id}, Metadata: {metadata}, Score: {score:.4f}\")\n\n# Save the database to disk\ndb.save()\nprint(f\"\\nDatabase saved to '{db_path}'\")\n\n# Load the database from disk\nloaded_db = NanoVectorDB(db_path, dim=4) # Re-initialize with path and dim\nloaded_db.load()\nprint(f\"Database loaded from '{db_path}'. Number of items: {len(loaded_db.store)}\")\n\n# Clean up database files (optional)\nif os.path.exists(db_path):\n    shutil.rmtree(db_path)\n    print(f\"Cleaned up database directory: {db_path}\")","lang":"python","description":"This quickstart demonstrates how to initialize NanoVectorDB, add vectors with associated metadata and unique IDs, perform a similarity search, and persist/load the database from disk. It also includes cleanup for the database directory."},"warnings":[{"fix":"Always pin to a specific patch version (`nano-vectordb==0.0.4.3`) and review release notes/GitHub changes when upgrading. Thoroughly test your application after any upgrade.","message":"As a pre-1.0 library (currently 0.0.x), NanoVectorDB's API is not stable. Method signatures, class names, or data structures returned by functions like `search` may change in minor or patch releases without explicit 'breaking change' warnings, requiring code adjustments.","severity":"breaking","affected_versions":"<1.0.0"},{"fix":"Ensure your input vectors are `numpy.array` instances of the correct `dim` and generated by an external embedding model. Example: `embedding_vector = model.encode('your text here')`.","message":"NanoVectorDB expects pre-computed embeddings as NumPy arrays. It does not provide functionality to generate embeddings from text or other data types itself. Users must use an external embedding model (e.g., from Hugging Face, OpenAI) to convert their data into vectors before adding them to the database.","severity":"gotcha","affected_versions":"All"},{"fix":"Evaluate your scale and performance requirements carefully. For production-grade or large-scale applications, consider more robust vector database solutions like Qdrant, Weaviate, Pinecone, or Faiss.","message":"NanoVectorDB is designed for lightweight, in-memory, or small-scale disk-persisted use cases. It is not built for large-scale, distributed, or high-throughput production environments and lacks features like sharding, replication, or advanced indexing strategies found in enterprise-grade vector databases.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Convert your list of floats into a NumPy array before passing it to NanoVectorDB. Example: `np.array([1.0, 2.0, 3.0])`.","cause":"Input vectors passed to `add` or `search` methods are Python lists instead of NumPy arrays.","error":"TypeError: 'list' object cannot be interpreted as an array"},{"fix":"Ensure all vectors added to the database and all query vectors have the exact same dimension (`dim`) as defined when the `NanoVectorDB` instance was created. If loading from disk, the `dim` parameter must match the original saved database.","cause":"The dimension of the vector being added or queried does not match the `dim` specified during `NanoVectorDB` initialization.","error":"ValueError: Vector dimension mismatch. Expected {expected_dim}, got {actual_dim}."},{"fix":"Ensure `db.save()` was called previously. Verify that the `db_path` provided to `NanoVectorDB` when loading is identical to the path used when saving, and that the directory and its contents still exist.","cause":"Attempting to load a database that has not been saved yet, or the specified `db_path` is incorrect, or the directory was deleted/moved.","error":"FileNotFoundError: [Errno 2] No such file or directory: '{db_path}/index.npy'"}]}