Pinecone Local is an in-memory Pinecone 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 uses the 2025-01 API version, which is not the latest stable version.
  • Pinecone Local is available in Docker only.
  • 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 as an index emulator or database emulator:
  • Index emulator - This approach uses the pinecone-index Docker image to create and configure indexes on startup. This is recommended when you want to quickly experiment with reading and writing data without needing to manage the index lifecycle.
    With index emulation, you can only read and write data to the indexes created at startup. You cannot create new indexes, list indexes, or run other operations that do not involve reading and writing data.
  • Database emulator - This approach uses the pinecone-local Docker image to emulate Pinecone Database more broadly. This is recommended when you want to test your production app or manually create and manage indexes.

​
Index emulator

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 Pinecone Local should create on startup. In this file, include the pinecone-index Docker image, a localhost port for the index to use, and other details:
services:
  dense-index:
    image: ghcr.io/pinecone-io/pinecone-index:latest
    container_name: dense-index
    environment:
      PORT: 5081
      INDEX_TYPE: serverless
      VECTOR_TYPE: dense
      DIMENSION: 2 
      METRIC: cosine
    ports:
      - "5081:5081"
    platform: linux/amd64
  sparse-index:
    image: ghcr.io/pinecone-io/pinecone-index:latest
    container_name: sparse-index
    environment:
      PORT: 5082
      INDEX_TYPE: serverless
      VECTOR_TYPE: sparse
      DIMENSION: 0
      METRIC: dotproduct
    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.
  • VECTOR_TYPE: Specify the type of vectors you will store in the index. Accepted values: dense or sparse.
    Sparse is supported only with serverless indexes.
  • DIMENSION: Specify the dimension of vectors you will store in the index.
    For sparse indexes, this must be set to 0.
  • METRIC: Specify the distance metric for calculating the similarity between vectors in the index. Accepted values for dense indexes: cosine, euclidean, or dotproduct. Accepted value for sparse indexes: dotproduct.
To start Pinecone Local, run the following command:
docker compose up -d
You’ll see a message with details about each index.

​
Database emulator

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-5090:5080-5090"
    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.

​
2. Develop your app

Running code against Pinecone Local is just like running code against your Pinecone account, with the following differences:
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. It initializes a client, creates a dense index and a sparse index, upserts records into the indexes, checks their record counts, and queries the indexes. 
from pinecone.grpc import PineconeGRPC, GRPCClientConfig
from pinecone import ServerlessSpec

# Initialize a client.
# API key is required, but the value does not matter.
# Host and port of the Pinecone Local instance
# is required when starting without indexes. 
pc = PineconeGRPC(
    api_key="pclocal", 
    host="http://localhost:5080" 
)                                    

# Create two indexes, one dense and one sparse
dense_index_name = "dense-index"
sparse_index_name = "sparse-index"

if not pc.has_index(dense_index_name):  
    dense_index_model = pc.create_index(
        name=dense_index_name,
        vector_type="dense",
        dimension=2,
        metric="cosine",
        spec=ServerlessSpec(cloud="aws", region="us-east-1"),
        deletion_protection="disabled",
        tags={"environment": "development"}
    )

print("Dense index model:\n", dense_index_model)

if not pc.has_index(sparse_index_name):  
    sparse_index_model = pc.create_index(
        name=sparse_index_name,
        vector_type="sparse",
        metric="dotproduct",
        spec=ServerlessSpec(cloud="aws", region="us-east-1"),
        deletion_protection="disabled",
        tags={"environment": "development"}
    )

print("\nSparse index model:\n", sparse_index_model)

# Target each index, disabling tls
dense_index_host = pc.describe_index(name=dense_index_name).host
dense_index = pc.Index(host=dense_index_host, grpc_config=GRPCClientConfig(secure=False))
sparse_index_host = pc.describe_index(name=sparse_index_name).host
sparse_index = pc.Index(host=sparse_index_host, grpc_config=GRPCClientConfig(secure=False))

# Upsert records into the dense index
dense_index.upsert(
    vectors=[
        {
            "id": "vec1", 
            "values": [1.0, -2.5],
            "metadata": {"genre": "drama"}
        },
        {
            "id": "vec2", 
            "values": [3.0, -2.0],
            "metadata": {"genre": "documentary"}
        },
        {
            "id": "vec3", 
            "values": [0.5, -1.5],
            "metadata": {"genre": "documentary"}
        }
    ],
    namespace="example-namespace"
)

# Upsert records into the sparse index
sparse_index.upsert(
    namespace="example-namespace",
    vectors=[
        {
            "id": "vec1",
            "sparse_values": {
                "values": [1.7958984, 0.41577148, 2.828125, 2.8027344, 2.8691406, 1.6533203, 5.3671875, 1.3046875, 0.49780273, 0.5722656, 2.71875, 3.0820312, 2.5019531, 4.4414062, 3.3554688],
                "indices": [822745112, 1009084850, 1221765879, 1408993854, 1504846510, 1596856843, 1640781426, 1656251611, 1807131503, 2543655733, 2902766088, 2909307736, 3246437992, 3517203014, 3590924191]
            },
            "metadata": {
                "chunk_text": "AAPL reported a year-over-year revenue increase, expecting stronger Q3 demand for its flagship phones.",
                "category": "technology",
                "quarter": "Q3"
            }
        },
        {
            "id": "vec2",
            "sparse_values": {
                "values": [0.4362793, 3.3457031, 2.7714844, 3.0273438, 3.3164062, 5.6015625, 2.4863281, 0.38134766, 1.25, 2.9609375, 0.34179688, 1.4306641, 0.34375, 3.3613281, 1.4404297, 2.2558594, 2.2597656, 4.8710938, 0.5605469],
                "indices": [131900689, 592326839, 710158994, 838729363, 1304885087, 1640781426, 1690623792, 1807131503, 2066971792, 2428553208, 2548600401, 2577534050, 3162218338, 3319279674, 3343062801, 3476647774, 3485013322, 3517203014, 4283091697]
            },
            "metadata": {
                "chunk_text": "Analysts suggest that AAPL'\''s upcoming Q4 product launch event might solidify its position in the premium smartphone market.",
                "category": "technology",
                "quarter": "Q4"
            }
        },
        {
            "id": "vec3",
            "sparse_values": {
                "values": [2.6875, 4.2929688, 3.609375, 3.0722656, 2.1152344, 5.78125, 3.7460938, 3.7363281, 1.2695312, 3.4824219, 0.7207031, 0.0826416, 4.671875, 3.7011719, 2.796875, 0.61621094],
                "indices": [8661920, 350356213, 391213188, 554637446, 1024951234, 1640781426, 1780689102, 1799010313, 2194093370, 2632344667, 2641553256, 2779594451, 3517203014, 3543799498, 3837503950, 4283091697]
            },
            "metadata": {
                "chunk_text": "AAPL'\''s strategic Q3 partnerships with semiconductor suppliers could mitigate component risks and stabilize iPhone production",
                "category": "technology",
                "quarter": "Q3"
            }
        }
    ]
)

# Check the number of records in each index
print("\nDense index stats:\n", dense_index.describe_index_stats())
print("\nSparse index stats:\n", sparse_index.describe_index_stats())

# Query the dense index with a metadata filter
dense_response = dense_index.query(
    namespace="example-namespace",
    vector=[3.0, -2.0],
    filter={"genre": {"$eq": "documentary"}},
    top_k=1,
    include_values=False,
    include_metadata=True
)

print("\nDense query response:\n", dense_response)

# Query the sparse index with a metadata filter
sparse_response = sparse_index.query(
    namespace="example-namespace",
    sparse_vector={
      "values": [1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0],
      "indices": [767227209, 1640781426, 1690623792, 2021799277, 2152645940, 2295025838, 2443437770, 2779594451, 2956155693, 3476647774, 3818127854, 4283091697]
    }, 
    filter={
        "quarter": {"$eq": "Q4"}
    },
    top_k=1,
    include_values=False,
    include_metadata=True
)

print("/nSparse query response:\n", sparse_response)

# Delete the indexes
pc.delete_index(name=dense_index_name)
pc.delete_index(name=sparse_index_name)

​
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: 
docker compose down

​
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: