Pinecone Python SDK first setup: env key, client, serverless index

Pinecone Python SDK: first working setup

Install

pip install pinecone

Use pip install "pinecone[grpc]" only if you want the gRPC data client. The plain package is the REST default and is what most agents want.

Authenticate from the environment

The client reads the PINECONE_API_KEY environment variable when you construct it with no arguments. Set the variable in your shell or secret store, never paste a key into code:

from pinecone import Pinecone

pc = Pinecone()

This is the documented pattern in the SDK README ("or omit and set PINECONEAPIKEY"). Passing a key literal into the constructor is how keys leak into repos and logs.

Create a serverless index

Index creation is async: the call submits a job, and the index takes a bit to become ready. Always pass a spec; omitting it raises TypeError: Pinecone.create_index() missing 1 required positional argument: 'spec'.

from pinecone import ServerlessSpec

pc.create_index(
    name="quickstart",
    dimension=1536,
    metric="cosine",
    spec=ServerlessSpec(cloud="aws", region="us-east-1"),
)

Match dimension to your embedding model (1536 for text-embedding-3-small, 3072 for text-embedding-3-large, 768 for many open models). Dimension and metric are frozen at creation; you cannot change them later, only recreate.

Get an index handle and write

index = pc.Index("quickstart")
index.upsert(vectors=[{"id": "vec1", "values": [0.1, 0.2, 0.3]}])

Wrap first writes in try/except on pinecone.exceptions.PineconeException so a bad key or wrong dimension surfaces as a readable error instead of a traceback.

Traps for agents

1. Old tutorials call pinecone.init(...). That was SDK v2. On the current SDK it raises module 'pinecone' has no attribute 'init'. The v3+ pattern is Pinecone() then pc.Index(name).
2. Creating the index and immediately upserting can hit a not-ready index. Poll pc.describe_index(name) until status.ready is true before writing (see the index-readiness skill).
3. The free tier caps you at a small number of serverless indexes per project; a 403 on create usually means quota, not a bug in your call.