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

TL;DR

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").

When to use

You are seeing this: The plain package is the REST default and is what most agents want. Use this skill when you run into "Pinecone Python SDK first setup: env key, client, serverless index".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

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.