Claude API Python SDK Installation Guide

Installing the Claude API Python SDK

If you're looking to install the official Python SDK for the Claude API, the short answer is: create a virtual environment, run pip install anthropic, set your API key as an environment variable, and make a test call. The whole process takes less than five minutes on a standard Python 3.8+ setup.

The rest of this guide walks through each step in detail, covers the environment setup choices that actually matter, and lists the most common installation errors with fixes — so you don't have to dig through GitHub issues when something breaks.

Prerequisites

Before installing, make sure you have:

• Python 3.8 or newer — check with python3 --version
• pip — usually bundled with Python, verify with pip --version
• An API key — either from Anthropic directly, or from a provider like SubToAPI that exposes Claude through a compatible HTTPS endpoint

If you're missing Python entirely, install it via your OS package manager (brew install python3, apt install python3, or the official installer on Windows).

Step 1: Create a Virtual Environment

Installing the SDK inside a virtual environment keeps your project dependencies isolated from the rest of your system. This avoids version conflicts if you have multiple Python projects on the same machine.

python3 -m venv .venv
source .venv/bin/activate   # macOS/Linux
.venv\Scripts\activate      # Windows

You'll know it worked because your shell prompt will show (.venv) at the start of the line.

Step 2: Install the SDK

With the virtual environment active, install the Anthropic Python package:

pip install anthropic

This pulls the anthropic package and its dependencies (mainly httpx for HTTP requests and pydantic for data validation). If you want a specific version pinned for reproducibility:

pip install anthropic==0.34.0

Check your requirements.txt or pyproject.toml and pin the version there once you've confirmed it works, so future installs stay consistent across machines and CI pipelines.

Step 3: Set Your API Key

The SDK looks for an environment variable by default. On macOS/Linux:

export ANTHROPIC_API_KEY="sk-ant-xxxxxxxx"

On Windows (PowerShell):

$env:ANTHROPIC_API_KEY="sk-ant-xxxxxxxx"

For anything beyond local testing, don't hardcode keys in source files. Use a .env file with python-dotenv, or your platform's secrets manager, and make sure .env is in .gitignore.

Step 4: Verify the Installation

Run a minimal script to confirm everything is wired correctly:

import os
from anthropic import Anthropic

client = Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])

response = client.messages.create(
    model="claude-3-5-sonnet-20241022",
    max_tokens=100,
    messages=[{"role": "user", "content": "Say hello in one sentence."}]
)

print(response.content[0].text)

If this prints a short greeting, the installation is complete and your key is valid. If it errors out, see the troubleshooting section below.

Common Installation Errors and Fixes

ModuleNotFoundError: No module named 'anthropic' Your virtual environment isn't activated, or you installed the package into a different Python interpreter than the one running your script. Run which python (or where python on Windows) and confirm it points inside .venv.

AuthenticationError: invalid x-api-key The key is missing, malformed, or expired. Double-check for extra whitespace or quotes when copying the key, and confirm the environment variable is actually exported in the shell session you're running from.

SSL certificate errors on corporate networks Usually caused by a corporate proxy intercepting HTTPS traffic. Set the HTTPS_PROXY environment variable or point httpx at your company's CA bundle via SSL_CERT_FILE.

Dependency conflicts with pydantic Older projects pinned to Pydantic v1 can clash with newer SDK versions that expect v2. Isolate the SDK in its own virtual environment or upgrade your other dependencies.

Managing the SDK in a Team or Production Setup

Once the basic install works, the next problem most teams hit is operational: how do multiple developers, services, or environments share Claude access without passing around one raw API key, tracking usage manually, or building their own billing and seat management?

This is the gap SubToAPI fills. It sits in front of your Claude access and issues scoped application keys (sub_live_...) per app, environment, or team member, so you're not sharing a single root credential across your codebase. Because the request format mirrors the standard Messages API, the same anthropic Python SDK pattern above works almost unchanged — you just point requests at SubToAPI's endpoint and swap in your sub_live_ key instead of a raw Anthropic key. You get streaming, tool use, and usage metadata per key, plus a dashboard for team seats, out of the box.

A minimal example hitting the SubToAPI endpoint directly with requests (useful if you want metadata or team-level routing without reworking SDK internals):

import os
import requests

response = requests.post(
    "https://api.subtoapi.app/v1/messages",
    headers={
        "Authorization": f"Bearer {os.environ['SUBTOAPI_KEY']}",
        "content-type": "application/json",
    },
    json={
        "model": "claude-3-5-sonnet-20241022",
        "max_tokens": 100,
        "messages": [{"role": "user", "content": "Say hello in one sentence."}],
    },
)

print(response.json())

Check the quickstart and messages docs for the full request/response reference, and the pricing page if you're evaluating Solo, Team, or Scale plans for a growing codebase. Sign up at /signup to generate a key and try it with a free trial.

Keeping Dependencies Up to Date

The SDK ships updates regularly as new models and features land. Periodically run:

pip install --upgrade anthropic

and re-run your test script after upgrading, since major version bumps occasionally change method signatures. If you're using a requirements.txt, update the pinned version deliberately rather than letting CI silently pull the latest release — that's a common source of "it worked yesterday" bugs.

Questions

Do I need a paid Anthropic account to install the SDK? No, the package itself is free to install via pip. You only need a valid API key to actually make calls, which requires billing setup on whichever platform issues the key.

Can I use the SDK with async code? Yes, the package includes an AsyncAnthropic client with the same method signatures as the sync version, designed for use with asyncio and frameworks like FastAPI.

Why does my script hang instead of returning an error? This usually means a network or proxy issue is silently blocking the HTTPS request. Add a timeout to your client initialization (Anthropic(api_key=key, timeout=30.0)) so failures surface quickly instead of hanging indefinitely.