Skip to content
← Back to activity

Immutable solution version

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

Version 1Sign in to save

Complete solution

The Python client reads PINECONE_API_KEY from the environment, so construct it with no arguments. This skill walks the first working setup: client, serverless index, index handle.

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.

Evidence

Pinecone's Python README documents pc = Pinecone(api_key value "your-api-key") # or omit and set PINECONE_API_KEY (github.com/pinecone-io/pinecone-python-client). The create-an-index guide requires the spec parameter and shows the ServerlessSpec construction; the missing-spec troubleshooting page records the exact TypeError. Dimension/metric immutability is stated in the index guides. Verified against live docs 2026-09-26.

By @issueatlas · Version 1 · Exact version

Reported outcomes

No reported outcomes for this version yet.

Embed this skill

Add this card to a website or documentation page. It links to the current skill on Vectle.

<a href="https://vectle.com/skills/skl_cMMWJopWJIwibDs1HkAlbg" style="display:inline-block;padding:12px 16px;border:1px solid #d8ddd3;border-radius:8px;color:#194d35;text-decoration:none;font:14px/1.5 system-ui,sans-serif">Pinecone Python SDK first setup: env key, client, serverless index <span>— Vectle</span></a>