Pinecone Local is an in-memory Pinecone Database emulator available as a Docker image.

This page shows you how to use Pinecone Local to develop your applications locally without connecting to your Pinecone account or incurring usage or storage fees.

Pinecone Local is not suitable for production. See Limitations for details.

This feature is in public preview.

​
Limitations

Pinecone Local has the following limitations:

  • Pinecone Local is available only as a Docker image.
  • Pinecone Local is an in-memory emulator and is not suitable for production. Records loaded into Pinecone Local do not persist after it is stopped.
  • Pinecone Local does not authenticate client requests. API keys are ignored.
  • Max number of records per index: 100,000.

Pinecone Local does not currently support the following features:

​
1. Start Pinecone Local

You can configure Pinecone Local to start with or without indexes.

  • Starting with indexes is recommended for getting started with Pinecone Database or quickly experimenting with reading and writing data. This approach use the pinecone-index Docker image.
  • Starting without indexes is recommended for testing your production app or creating and managing indexes. This approach uses the pinecone-local Docker image.

​
Start with indexes

Make sure Docker is installed and running on your local machine.

Create a docker-compose.yaml file that defines a service for each index that you want Pinecone Local to create on startup, including the pinecone-index Docker image, the host and port that the index with run on, the type of index, and the dimension and distance metric of the index:

services:
  index1:
    image: ghcr.io/pinecone-io/pinecone-index:latest
    environment:
      PORT: 5080
      INDEX_TYPE: serverless
      DIMENSION: 2 
      METRIC: cosine
    ports:
      - "5081:5081"
    platform: linux/amd64
  index2:
    image: ghcr.io/pinecone-io/pinecone-index:latest
    environment:
      PORT: 5081
      INDEX_TYPE: pod
      DIMENSION: 2 
      METRIC: dot-product
    ports:
      - "5082:5082"
    platform: linux/amd64

For each index, update the environment variables as needed:

  • PORT: Specify the port number for the index to listen on.
  • INDEX_TYPE: Specify the type of Pinecone index to create. Accepted values: serverless or pod.
  • DIMENSION: Specify the dimension of vectors you will store in the index.
  • METRIC: Specify the distance metric for calculating the similarity between vectors in the index. Accepted values: cosine, euclidean, or dot-product.

To start Pinecone Local, run the following command:

docker compose up -d

You’ll see a message with details about each index, including the port it listens on:

 ✔ Container pclocal-index1-1                                                                                                                            Created0.1s 
 ✔ Container pclocal-index2-1                                                                                                                            Created0.1s 
Attaching to pclocal-index1-1, pclocal-index2-1
pclocal-index1-1  | 2024-09-11T17:55:01 [INFO] - Serving a serverless pinecone index with dimension 2 and metric cosine on port 5081
pclocal-index2-1  | 2024-09-11T17:55:01 [INFO] - Serving a pod pinecone index with dimension 2 and metric dot-product on port 5082

​
Start without indexes

Make sure Docker is installed and running on your local machine.

Create a docker-compose.yaml file that defines a service for Pinecone local, including the pinecone-local Docker image, the host and port that Pinecone Local will run on and the range of ports that will be available for indexes:

services:
  pinecone:
    image: ghcr.io/pinecone-io/pinecone-local:latest
    environment: 
      PORT: 5080
      PINECONE_HOST: localhost
    ports: 
      - "5080-6000:5080-6000"
    platform: linux/amd64

To start Pinecone Local, run the following command:

docker compose up -d

You’ll see a message with details about the Pinecone Local instance:

[+] Building 0.0s (0/0)                                                                                                                                  docker:desktop-linux
[+] Running 3/3
 ✔ Network pclocal_default         Created       0.0s
 ✔ Container pclocal-pinecone-1    Started       0.1s

​
2. Develop your app

Running code against Pinecone Local is just like running code against your Pinecone account, with the following differences:

  • Pinecone Local does not authenticate client requests. API keys are ignored.

  • Pinecone Local requires Python SDK v4.1.2 or later, Node.js SDK v3.0.x or later, and Go SDK v1.1.1 or later. The Java SDK and .NET SDK are not yet supported.

Be sure to review the limitations of Pinecone Local before using it for development or testing.

Example

The following example assumes that you have started Pinecone Local without indexes:

​
3. Stop Pinecone Local

Pinecone Local is an in-memory emulator. Records loaded into Pinecone Local do not persist after Pinecone Local is stopped.

To stop and remove the resources for Pinecone Local, run the following command:

​
Moving from Pinecone Local to your Pinecone account

When you’re ready to run your application against your Pinecone account, be sure to do the following:

Was this page helpful?

Evaluate answersAutomated testing