Skip to main content
Weaviate Docs (migrated from docs.weaviate.io) Docs

Search documentation

Type to search this documentation.

On this pageOverview

Local instances

Follow these steps to connect to a locally hosted Weaviate instance.

Local connection URL

Section titled “Local connection URL”

Docker instances default to http://localhost:8080. The gRPC port, 50051, is also on localhost.

If your instance runs on Kubernetes, see the host and port values in your Helm chart's values.yaml file.

No authentication enabled

Section titled “No authentication enabled”

To connect to a local instance without authentication, follow these examples.

Python
import weaviate

client = weaviate.connect_to_local()

print(client.is_ready())
JavaScript/TypeScript
const client = await weaviate.connectToLocal()

console.log(client)
Go
package main

import (
  "context"
  "fmt"

  "github.com/weaviate/weaviate-go-client/v5/weaviate"
)

// Create the client
func CreateClient() {
  cfg := weaviate.Config{
    Host:       "localhost:8080",
    Scheme:     "http",
        Headers:    nil,
  }

  client, err := weaviate.NewClient(cfg)
  if err != nil {
    fmt.Println(err)
  }

  // Check the connection
  live, err := client.Misc().LiveChecker().Do(context.Background())
  if err != nil {
    panic(err)
  }
  fmt.Printf("%v", live)

}

func main() {
  CreateClient()
}
Java
WeaviateClient client = WeaviateClient.connectToLocal();

System.out.println(client.isReady()); // Should print: `True`

client.close(); // Free up resources
C#
WeaviateClient client = await Connect.Local();

var isReady = await client.IsReady();
Console.WriteLine(isReady);
cURL
curl http://localhost:8080/v1/meta | jq

Change the URL or port

Section titled “Change the URL or port”

To change the default URL or port number, follow these examples.

Python
import weaviate

client = weaviate.connect_to_local(
    host="127.0.0.1",  # Use a string to specify the host
    port=8080,
    grpc_port=50051,
)

print(client.is_ready())
JavaScript/TypeScript
const client = await weaviate.connectToLocal(
 {
    host: "127.0.0.1",   // URL only, no http prefix
    port: 8080,
    grpcPort: 50051,     // Default is 50051, WCD uses 443
 })

async function main() {
  console.log(await client.isReady())
  await client.close()
}

main()
Go
package main

import (
  "context"
  "fmt"

  "github.com/weaviate/weaviate-go-client/v5/weaviate"
)

// Create the client
func CreateClient() {
  cfg := weaviate.Config{
    Host:       "localhost:8080",
    Scheme:     "http",
        Headers:    nil,
        // The Go client doesn't use the gRPC port
  }

  client, err := weaviate.NewClient(cfg)
  if err != nil {
    fmt.Println(err)
  }

  // Check the connection
  live, err := client.Misc().LiveChecker().Do(context.Background())
  if err != nil {
    panic(err)
  }
  fmt.Printf("%v", live)

}

func main() {
  CreateClient()
}
Java
WeaviateClient client = WeaviateClient
    .connectToLocal(config -> config.host("127.0.0.1").port(8080));

System.out.println(client.isReady()); // Should print: `True`

client.close(); // Free up resources
C#
WeaviateClient client = await WeaviateClientBuilder
    .Custom(
        restEndpoint: "127.0.0.1",
        restPort: "8080",
        grpcEndpoint: "127.0.0.1",
        grpcPort: "50051",
        useSsl: false
    )
    .BuildAsync();

var isReady = await client.IsReady();
Console.WriteLine(isReady);
cURL
curl http://localhost:8080/v1/meta | jq
# The cURL connection doesn't use the gRPC port

Authentication enabled

Section titled “Authentication enabled”

To authenticate with a Weaviate API key, follow these examples.

Python
import weaviate
from weaviate.classes.init import Auth

# Best practice: store your credentials in environment variables
weaviate_api_key = os.environ["WEAVIATE_API_KEY"]
JavaScript/TypeScript
// Set this environment variable
// WEAVIATE_LOCAL_API_KEY   your Weaviate instance API key

const weaviateKey = process.env.WEAVIATE_LOCAL_API_KEY as string

const client = await weaviate.connectToLocal(
   { 
    port:8099,
    grpcPort:50052, 
    authCredentials: new weaviate.ApiKey(weaviateKey)
  }
)

console.log(client)
Go
// Set this environment variable
// WEAVIATE_API_KEY  your Weaviate instance API key

package main

import (
  "context"
  "fmt"
  "os"

  "github.com/weaviate/weaviate-go-client/v5/weaviate"
    "github.com/weaviate/weaviate-go-client/v5/weaviate/auth"
)

// Create the client
func CreateClient() {
  cfg := weaviate.Config{
    Host:       "localhost:8080",
    Scheme:     "http",
        AuthConfig: auth.ApiKey{Value: os.Getenv("WEAVIATE_API_KEY")},
        Headers:    nil,
  }

  client, err := weaviate.NewClient(cfg)
  if err != nil {
    fmt.Println(err)
  }

  // Check the connection
  live, err := client.Misc().LiveChecker().Do(context.Background())
  if err != nil {
    panic(err)
  }
  fmt.Printf("%v", live)

}

func main() {
  CreateClient()
}
Java
// Best practice: store your credentials in environment variables
final String weaviateApiKey = System.getenv("WEAVIATE_LOCAL_API_KEY");

WeaviateClient client =
    WeaviateClient.connectToLocal(config -> config.host("127.0.0.1")
        .port(8099)
        .grpcPort(50052)
        .authentication(Authentication.apiKey(weaviateApiKey)));

System.out.println(client.isReady()); // Should print: `True`

client.close(); // Free up resources
C#
// Best practice: store your credentials in environment variables
string weaviateApiKey = Environment.GetEnvironmentVariable("WEAVIATE_LOCAL_API_KEY");

WeaviateClient client = await Connect.Local(
    hostname: "127.0.0.1",
    restPort: 8099,
    grpcPort: 50052,
    credentials: Auth.ApiKey(weaviateApiKey)
);

var isReady = await client.IsReady();
Console.WriteLine(isReady);
cURL
# Set this environment variable
# WEAVIATE_API_KEY  your Weaviate instance API key

curl http://localhost:8080/v1/meta -H "Authorization: Bearer ${WEAVIATE_API_KEY}" | jq

OIDC authentication

Section titled “OIDC authentication”

For additional client examples, see OIDC authentication.

Third party API keys

Section titled “Third party API keys”

Integrations that use external APIs often need API keys. To add third party API keys, follow these examples:

Python
import os
import weaviate

# Best practice: store your credentials in environment variables
cohere_api_key = os.environ["COHERE_API_KEY"]

client = weaviate.connect_to_local(
    headers={
        "X-Cohere-Api-Key": cohere_api_key
    }
)

print(client.is_ready())
JavaScript/TypeScript
// Set this environment variable
// COHERE_API_KEY    your Cohere API key

const cohereKey = process.env.COHERE_API_KEY as string

const client = await weaviate.connectToLocal(
  {
    headers: {
     'X-Cohere-Api-Key':  cohereKey,
    }
  }
)

console.log(client)
Go
// Set this environment variable
// COHERE_API_KEY    your Cohere API key

package main

import (
  "context"
  "fmt"
  "os"

  "github.com/weaviate/weaviate-go-client/v5/weaviate"
)

// Create the client
func CreateClient() {
  cfg := weaviate.Config{
    Host:       "localhost:8080",
    Scheme:     "http",
        Headers:     map[string]string{
            "X-Cohere-Api-Key": os.Getenv("WEAVIATE_COHERE_KEY"),
        },
  }

  client, err := weaviate.NewClient(cfg)
  if err != nil {
    fmt.Println(err)
  }

  // Check the connection
  live, err := client.Misc().LiveChecker().Do(context.Background())
  if err != nil {
    panic(err)
  }
  fmt.Printf("%v", live)

}

func main() {
  CreateClient()
}
Java
// Best practice: store your credentials in environment variables
final String cohereApiKey = System.getenv("COHERE_API_KEY");

WeaviateClient client = WeaviateClient.connectToLocal(
    config -> config.setHeaders(Map.of("X-Cohere-Api-Key", cohereApiKey)));

System.out.println(client.isReady()); // Should print: `True`

client.close(); // Free up resources
C#
// Best practice: store your credentials in environment variables
string cohereApiKey = Environment.GetEnvironmentVariable("COHERE_API_KEY");

WeaviateClient client = await WeaviateClientBuilder
    .Local(hostname: "localhost", restPort: 8080, grpcPort: 50051, useSsl: false)
    .WithHeaders(new Dictionary<string, string> { { "X-Cohere-Api-Key", cohereApiKey } })
    .BuildAsync();

var isReady = await client.IsReady();
Console.WriteLine(isReady);
cURL
# Set this environment variable
# COHERE_API_KEY    your Cohere API key

curl http://localhost:8080/v1/meta \
-H 'Content-Type: application/json' \
-H "X-Cohere-Api-Key: ${COHERE_API_KEY}" | jq

Environment variables

Section titled “Environment variables”

Environment variables keep sensitive details out of your source code. Your application imports the information to runtime.

Set an environment variable.

In these examples, the environment variable names are in UPPER_CASE.

Bash/Zsh
export WEAVIATE_URL="http://localhost:8080"
export WEAVIATE_API_KEY="sAmPleKEY8FwELJILn0YDRG9gjy4hReqfInz"
Windows PowerShell
$Env:WEAVIATE_URL="http://localhost:8080"
$Env:WEAVIATE_API_KEY="sAmPleKEY8FwELJILn0YDRG9gjy4hReqfInz"
Windows Command Prompt
set WEAVIATE_URL=http://localhost:8080
set WEAVIATE_API_KEY=sAmPleKEY8FwELJILn0YDRG9gjy4hReqfInz
Import an environment variable.
Python
weaviate_url = os.getenv("WEAVIATE_URL")
weaviate_key = os.getenv("WEAVIATE_API_KEY")
JavaScript/TypeScript
const weaviateUrl = process.env.WEAVIATE_URL;
const weaviateKey = process.env.WEAVIATE_API_KEY;
Go
weaviateUrl := os.Getenv("WEAVIATE_URL")
weaviateKey := os.Getenv("WEAVIATE_API_KEY")

gRPC timeouts

Section titled “gRPC timeouts”

The Python client v4 and TypeScript client v3 use gRPC. The gRPC protocol is sensitive to network delay. If you encounter connection timeouts, adjust the timeout values for initialization, queries, and insertions.

Python
import weaviate
from weaviate.classes.init import AdditionalConfig, Timeout

client = weaviate.connect_to_local(
    port=8080,
    grpc_port=50051,
    additional_config=AdditionalConfig(
        timeout=Timeout(init=30, query=60, insert=120)  # Values in seconds
    )
)

print(client.is_ready())
JavaScript/TypeScript
const client = await weaviate.connectToLocal(
   {  timeout: { init: 30, query: 60, insert: 120 }, } // Values in seconds
)

console.log(client)
Java
WeaviateClient client =
    WeaviateClient.connectToLocal(config -> config.timeout(30, 60, 120)); // Values in seconds

System.out.println(client.isReady()); // Should print: `True`

client.close(); // Free up resources
C#
WeaviateClient client = await Connect.Local(
    initTimeout: TimeSpan.FromSeconds(30),
    queryTimeout: TimeSpan.FromSeconds(60),
    insertTimeout: TimeSpan.FromSeconds(120)
);

var isReady = await client.IsReady();
Console.WriteLine(isReady);

Questions and feedback

Section titled “Questions and feedback”

Have a question or feedback? Here's how to reach us.

Community Forum

Ask questions and connect with other developers on our Community forum.

Support

Weaviate Cloud user or customer? Find the right channel on the Support page.

Suggest an edit

Propose a replacement for this page. The site team reviews it before applying any changes.

Export
Documentation menu