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

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