Code beginner · 3 min read

How to create Pinecone index in python

Direct answer

Use the Pinecone Python SDK to initialize a client with your API key and call pinecone.create_index() with your index name, dimension, and metric to create a Pinecone index.

Setup

Install

bash

pip install pinecone-client

Env vars

PINECONE_API_KEYPINECONE_ENVIRONMENT

Imports

python

import os
import pinecone

Examples

inCreate an index named 'example-index' with dimension 128 and cosine similarity metric.

outIndex 'example-index' created successfully with dimension 128 and metric 'cosine'.

inCreate an index 'text-embeddings' with dimension 1536 and euclidean distance metric.

outIndex 'text-embeddings' created successfully with dimension 1536 and metric 'euclidean'.

inAttempt to create an index with an existing name 'example-index'.

outError: Index 'example-index' already exists.

Integration steps

Install the Pinecone Python client with pip.
Set environment variables for PINECONE_API_KEY and PINECONE_ENVIRONMENT.
Import pinecone and initialize it with your API key and environment.
Call pinecone.create_index() with the index name, dimension, and similarity metric.
Verify the index creation by listing existing indexes or checking for errors.

Full code

python

import os
import pinecone

# Initialize Pinecone client
pinecone.init(
    api_key=os.environ["PINECONE_API_KEY"],
    environment=os.environ["PINECONE_ENVIRONMENT"]
)

index_name = "example-index"
dimension = 128
metric = "cosine"  # Options: 'cosine', 'euclidean', 'dotproduct'

# Create the index
if index_name not in pinecone.list_indexes():
    pinecone.create_index(name=index_name, dimension=dimension, metric=metric)
    print(f"Index '{index_name}' created successfully.")
else:
    print(f"Index '{index_name}' already exists.")

output

Index 'example-index' created successfully.

API trace

Request

json

{"name": "example-index", "dimension": 128, "metric": "cosine"}

Response

json

{"status": "Success", "index_name": "example-index", "dimension": 128, "metric": "cosine"}

ExtractCheck if the index name is in pinecone.list_indexes() or catch exceptions from create_index()

Variants

Async version ›

Use when integrating Pinecone index creation in an async Python application to avoid blocking.

python

import os
import asyncio
import pinecone

async def create_index_async():
    pinecone.init(api_key=os.environ["PINECONE_API_KEY"], environment=os.environ["PINECONE_ENVIRONMENT"])
    index_name = "async-index"
    dimension = 128
    metric = "cosine"

    indexes = pinecone.list_indexes()
    if index_name not in indexes:
        await pinecone.create_index(name=index_name, dimension=dimension, metric=metric)
        print(f"Index '{index_name}' created asynchronously.")
    else:
        print(f"Index '{index_name}' already exists.")

asyncio.run(create_index_async())

Create index with metadata config ›

Use when you want to enable filtering on metadata fields in your Pinecone index.

python

import os
import pinecone

pinecone.init(api_key=os.environ["PINECONE_API_KEY"], environment=os.environ["PINECONE_ENVIRONMENT"])

index_name = "meta-index"
dimension = 256
metric = "dotproduct"

# Create index with metadata config
if index_name not in pinecone.list_indexes():
    pinecone.create_index(
        name=index_name,
        dimension=dimension,
        metric=metric,
        metadata_config={"indexed": ["genre", "author"]}
    )
    print(f"Index '{index_name}' with metadata config created.")
else:
    print(f"Index '{index_name}' already exists.")

Performance

Latency~200-500ms per create_index call depending on network and region

CostCreating an index is free; costs incur on storage and query usage

Rate limitsDefault limits allow up to 20 index creations per minute per account

Keep index dimension as low as possible to reduce storage and query costs
Reuse existing indexes instead of creating new ones frequently
Use appropriate metric (cosine, euclidean, dotproduct) for your embedding type

Approach	Latency	Cost/call	Best for
Standard create_index	~300ms	Free	Simple synchronous index creation
Async create_index	~300ms	Free	Non-blocking index creation in async apps
Create with metadata config	~400ms	Free	Indexes requiring metadata filtering

✓

Quick tip

Always check if the index already exists with <code>pinecone.list_indexes()</code> before creating to avoid errors.

⚠

Common mistake

Forgetting to initialize Pinecone with both API key and environment before calling <code>create_index()</code> causes authentication errors.

Verified 2026-04

Verify ↗