# 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.