:::callout{intent="warning" title="Experimental"} Embedded Weaviate is **experimental** software. APIs and parameters may change. ::: Embedded Weaviate is a deployment model that runs a Weaviate instance from your application code rather than from a stand-alone Weaviate server installation. When Embedded Weaviate starts for the first time, it creates a permanent datastore in the location set in your `persistence_data_path`. When your client exits, the Embedded Weaviate instance also exits, but the data persists. The next time the client runs, the client starts a new instance of Embedded Weaviate. New Embedded Weaviate instances use the data that is saved in the datastore. ## Start an Embedded Weaviate instance :::code-group{sync="languages"} ```python title="Python" import weaviate import os client = weaviate.connect_to_embedded( version=weaviate_version, # e.g. version="1.33.0" headers={ "X-OpenAI-Api-Key": os.getenv("OPENAI_API_KEY") # Replace with your API key }, environment_variables={"LOG_LEVEL": "error"} # Reduce amount of logs ) # Add your client code here. ``` ::: :::callout{intent="tip" title="Set the log level to reduce verbosity"} Embedded Weaviate can emit a lot of log messages. To reduce the amount of logs, set the `LOG_LEVEL` environment variable to `error` or `warning`, as shown in the example above. ::: When you exit the client, the Embedded Weaviate instance also exits. ### Custom connection configuration To pass additional configuration details to your embedded instance, use a custom connection: :::code-group{sync="languages"} ```python title="Python" import weaviate from weaviate.embedded import EmbeddedOptions import os client = weaviate.WeaviateClient( embedded_options=EmbeddedOptions( additional_env_vars={ "ENABLE_MODULES": "backup-filesystem,text2vec-openai,text2vec-cohere,text2vec-huggingface,ref2vec-centroid,generative-openai,qna-openai", "BACKUP_FILESYSTEM_PATH": "/tmp/backups" } ) # Add additional options here (see Python client docs for syntax) ) client.connect() # Call `connect()` to connect to the server when you use `WeaviateClient` # Add your client code here. # Uncomment the next line to exit the Embedded Weaviate server. # client.close() ``` ::: ## Configuration options To configure Embedded Weaviate, set these variables in your instantiation code or pass them as parameters when you invoke your client. You can also pass them as system environment variables. All parameters are optional. | Parameter | Type | Default | Description | | :---------------------- | :------ | :---------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `additional_env_vars` | string | None. | Pass additional environment variables, such as API keys, to the server. | | `binary_path` | string | varies | Binary download directory. If the binary is not present, the client downloads the binary.

If `XDG_CACHE_HOME` is set, its value is used verbatim as the default. No subdirectory is appended, so `XDG_CACHE_HOME=/foo` makes the default exactly `/foo`.

If `XDG_CACHE_HOME` is not set, the default is: `~/.cache/weaviate-embedded/` | | `grpc_port` | integer | 50060 | The Weaviate server gRPC port. The client passes this value to the server as `GRPC_PORT`. | | `hostname` | string | 127.0.0.1 | Hostname or IP address | | `persistence_data_path` | string | varies | Data storage directory.

If `XDG_DATA_HOME` is set, its value is used verbatim as the default. No subdirectory is appended, so `XDG_DATA_HOME=/foo` makes the default exactly `/foo`.

If `XDG_DATA_HOME` is not set, the default is: `~/.local/share/weaviate` | | `port` | integer | 8079 | The Weaviate server request port. | | `version` | string | A version pinned in the client (see note) | Specify the version with one of the following:
-`"latest"`
- The version number as a string: `"1.19.6"`
- The URL of a Weaviate binary ([See below](installation-guides-embedded.md#file-url)) | :::callout{intent="note" title="Set `version` explicitly"} If you do not set `version`, Embedded Weaviate does not run the latest Weaviate release. The client falls back to a single Weaviate version that is fixed in the client source code when that client release is published. That pin only moves when the client is released again, so it can be several Weaviate minor releases behind the current one, and upgrading your client can also change which Weaviate version your embedded instance runs. Set `version` explicitly so you control which server version you get. Use `"latest"` to resolve the newest Weaviate release at startup, or pin a version number such as `"1.19.6"` for a reproducible environment. The version in use is printed in the embedded server startup logs. ::: :::callout{intent="warning" title="Do not modify `XDG_CACHE_HOME` or `XDG_DATA_HOME`"} The `XDG_DATA_HOME` and `XDG_CACHE_HOME` environment variables are widely used system variables. If you modify them, you may break other applications. ::: ## Default modules The following modules are enabled by default: - `generative-openai` - `qna-openai` - `ref2vec-centroid` - `text2vec-cohere` - `text2vec-huggingface` - `text2vec-openai` To enable additional modules, add them to your instantiation code. For example, to add the `backup-s3` module, instantiate your client like this: :::code-group{sync="languages"} ```python title="Python" import weaviate from weaviate.embedded import EmbeddedOptions import os client = weaviate.WeaviateClient( embedded_options=EmbeddedOptions( additional_env_vars={ "ENABLE_MODULES": "backup-filesystem,text2vec-openai,text2vec-cohere,text2vec-huggingface,ref2vec-centroid,generative-openai,qna-openai", "BACKUP_FILESYSTEM_PATH": "/tmp/backups" } ) # Add additional options here. For syntax, see the Python client documentation. ) # Run your client code in a context manager or call client.close() # before exiting the client to avoid connection errors. client.connect() # Call `connect()` to connect to the server when you use `WeaviateClient` # Add your client code here. ``` ::: ## Binary sources Weaviate Database releases include executable Linux binaries. When you instantiate an Embedded Weaviate client, the client checks for local copies of the binary packages. If the client finds the binary files, it runs them to create a temporary Weaviate instance. If not, the client downloads the binaries and saves them in your `binary_path` directory. The Embedded Weaviate instance goes away when your client exits. However, the client does not delete the binary files. The next time your client runs, it checks for the binaries and uses the saved binaries if they exist. ### File list For a list of the files that are included in a release, see the Assets section of the Release Notes page for that release on [GitHub](https://github.com/weaviate/weaviate/releases). ### File URL To get the URL for a particular binary archive file, follow these steps: 1. Find the Weaviate Database release you want on the [Release Notes](../releases/index.md) page. 2. Click to the release notes for that version. The Assets section includes `linux-amd64` and `linux-arm64` binaries in `tar.gz` format. 3. Copy the link to the full URL of the `tar.gz` file for your platform. For example, the URL for the Weaviate `1.19.6` `AMD64` binary is: `https://github.com/weaviate/weaviate/releases/download/v1.19.6/weaviate-v1.19.6-linux-amd64.tar.gz`. ## Functional overview Weaviate Database usually runs as a stand-alone server that clients connect to in order to access data. An Embedded Weaviate instance is a process that runs in conjunction with a client script or application. Embedded Weaviate instances can access a persistent datastore, but the instances exit when the client exits. When your client runs, it checks for a stored Weaviate binary. If it finds one, the client uses that binary to create an Embedded Weaviate instance. If not, the client downloads the binary. The instance also checks for an existing data store. Clients reuse the same data store, updates persist between client invocations. When you exit the client script or application, the Embedded Weaviate instance also exits: - Scripts: The Embedded Weaviate instance exits when the script exits. - Applications: The Embedded Weaviate instance exits when the application exits. - Jupyter Notebooks: The Embedded Weaviate instance exits when the Jupyter notebook is no longer active. ## Embedded server output The embedded server pipes `STDOUT` and `STDERR` to the client. To redirect `STDERR` in a command terminal, run your script like this: ```bash python3 your_embedded_client_script.py 2>/dev/null ``` ## Supported Environments Embedded Weaviate is supported on Linux and macOS. ## Client languages Embedded Weaviate is supported for Python and TypeScript clients. ### Python clients Embedded Weaviate is built into the [Python client](../client-libraries/python.md), so there is no separate package to install. The Python client requires Weaviate `v1.23.7` or later. ### TypeScript clients The embedded TypeScript client is no longer a part of the standard TypeScript client. The embedded client has additional dependencies that are not included in the standard client. However, the embedded client extends the original TypeScript client so after you instantiate an Embedded Weaviate instance, the embedded TypeScript client works the same way as the standard client. To install the embedded TypeScript client, run this command: ``` npm install weaviate-ts-embedded ``` The TypeScript clients are in these GitHub repositories: - [Embedded TypeScript client](https://github.com/weaviate/typescript-embedded) - [Standard TypeScript client](https://github.com/weaviate/typescript-client) ## Questions and feedback Have a question or feedback? Here's how to reach us. ::::card-grid :::card{title="Community Forum" href="https://forum.weaviate.io/c/support" icon="messages-square"} Ask questions and connect with other developers on our **Community forum**. ::: :::card{title="Support" href="/guides/support-overview" icon="life-buoy"} Weaviate Cloud user or customer? Find the right channel on the **Support page**. ::: :::: ## Related pages - [Agents](./agents-index.md) - [AI-assisted Weaviate code generation](./ai-assisted-vibe-coding-index.md) - [APIs](./apis-index.md) - [Authorization and authentication](./authorization-and-authentication-index.md) - [Benchmarks](./benchmarks-index.md) - [Best practices](./best-practices-index.md) - [Client libraries](./clients-index.md) - [Client Libraries / SDKs](./client-libraries-index.md) - [Cloud](./cloud-index.md) - [Cloud account management](./cloud-account-management-index.md) # Agent Instructions This portal answers questions programmatically. To receive a synthesized, source-cited answer instead of crawling page by page, append the `?ask=` query parameter to any page URL on this site: /guides/quickstart?ask=how+do+I+authenticate Optional parameters: - `&goal=` steers the answer toward your objective (e.g. `&goal=write+a+python+client`). - `&version=