Slow imports

[g0t4]

timing

Is it really ok that it takes 209ms to import even a single type from this package?

This feels like the perfect task for Claude Code?!

I have no background in the best way to solve this issue, I just know this feels wrong for such a central dependency. And common, let's be honest, this is a glorified HTTP client.

This destroys downstream performance in packages like langchain_anthropic which wind up taking 300ms+ for imports alone, just to make a simple http call to generate a completion!

python3 -X importtime -c "import anthropic"

...
import time:        66 |      69232 |   anthropic.lib.tools
...
import time:       506 |     116232 |   anthropic.types
...
import time:       329 |     209401 | anthropic

python3 -X importtime -c "from anthropic.types.image_block_param import ImageBlockParam"
...
import time:       313 |     208162 |     anthropic
import time:         7 |     208169 |   anthropic.types
import time:        10 |     208178 | anthropic.types.image_block_param

I'd hate to think that just because it's python it's ok to ignore optimizations... but, perhaps my expectations are miscalibrated, I'm open to that possibility. Am I crazy?

Claude seems to agree

I've got Claude working on some ideas for me! I don't have time to do this myself, but, Claude is killing it with perf profiling and I bet will find the spots we can get some big wins.

Gotta tame the explosion of types and importing all of them on every import basically

[g0t4]

@claude can you propose improvements?

[g0t4]

ok much better already! timing down to 130ms (from 200ms to 300ms) for import anthropic by lazy loading and limiting some types for type checking (this was Claude's suggestion and I have yet to verify it is all necessary, for now I just wanted to test and verify it is worth looking into)

This is a 35% to 60% reduction for src/anthropic/__init__.py (import anthropic) alone!

Given this is mostly generated code, if the generator were updated this change could be applied globally for global wins (or at least wins in all the __init__.pys where many modules are re-exported)

Can prioritize __init__.pys with this:

fd __init__.py --exec dirname | string replace --regex "^./" "import " | string replace --all "/" "." | sort | gxargs -t -I_ -- fish -ic "python3 -X importtime -c '_' 2>&1 | tail -1"
# output:
fish -ic 'python3 -X importtime -c '\''import src.anthropic'\'' 2>&1 | tail -1'
import time:       141 |     118264 | src.anthropic
fish -ic 'python3 -X importtime -c '\''import src.anthropic._utils'\'' 2>&1 | tail -1'
import time:         7 |     114666 | src.anthropic._utils
fish -ic 'python3 -X importtime -c '\''import src.anthropic.lib'\'' 2>&1 | tail -1'
import time:         7 |     114770 | src.anthropic.lib
fish -ic 'python3 -X importtime -c '\''import src.anthropic.lib._extras'\'' 2>&1 | tail -1'
import time:        68 |     115443 | src.anthropic.lib._extras
fish -ic 'python3 -X importtime -c '\''import src.anthropic.lib.bedrock'\'' 2>&1 | tail -1'
import time:        70 |     251752 | src.anthropic.lib.bedrock
fish -ic 'python3 -X importtime -c '\''import src.anthropic.lib.streaming'\'' 2>&1 | tail -1'
import time:     10367 |     233769 | src.anthropic.lib.streaming
fish -ic 'python3 -X importtime -c '\''import src.anthropic.lib.tools'\'' 2>&1 | tail -1'
import time:        69 |     235450 | src.anthropic.lib.tools
fish -ic 'python3 -X importtime -c '\''import src.anthropic.lib.vertex'\'' 2>&1 | tail -1'
import time:        72 |     250638 | src.anthropic.lib.vertex
fish -ic 'python3 -X importtime -c '\''import src.anthropic.resources'\'' 2>&1 | tail -1'
import time:        74 |     245359 | src.anthropic.resources
fish -ic 'python3 -X importtime -c '\''import src.anthropic.resources.beta'\'' 2>&1 | tail -1'
import time:         7 |     244451 | src.anthropic.resources.beta
fish -ic 'python3 -X importtime -c '\''import src.anthropic.resources.beta.messages'\'' 2>&1 | tail -1'
import time:         7 |     247066 | src.anthropic.resources.beta.messages
fish -ic 'python3 -X importtime -c '\''import src.anthropic.resources.beta.skills'\'' 2>&1 | tail -1'
import time:         7 |     246122 | src.anthropic.resources.beta.skills
fish -ic 'python3 -X importtime -c '\''import src.anthropic.resources.messages'\'' 2>&1 | tail -1'
import time:         7 |     246781 | src.anthropic.resources.messages
fish -ic 'python3 -X importtime -c '\''import src.anthropic.types'\'' 2>&1 | tail -1'
import time:         7 |     113725 | src.anthropic.types
fish -ic 'python3 -X importtime -c '\''import src.anthropic.types.beta'\'' 2>&1 | tail -1'
import time:       327 |     141756 | src.anthropic.types.beta
fish -ic 'python3 -X importtime -c '\''import src.anthropic.types.beta.messages'\'' 2>&1 | tail -1'
import time:       117 |     145650 | src.anthropic.types.beta.messages
fish -ic 'python3 -X importtime -c '\''import src.anthropic.types.beta.skills'\'' 2>&1 | tail -1'
import time:        82 |     142197 | src.anthropic.types.beta.skills
fish -ic 'python3 -X importtime -c '\''import src.anthropic.types.messages'\'' 2>&1 | tail -1'
import time:        92 |     114832 | src.anthropic.types.messages
fish -ic 'python3 -X importtime -c '\''import src.anthropic.types.shared'\'' 2>&1 | tail -1'
import time:         6 |     114797 | src.anthropic.types.shared
fish -ic 'python3 -X importtime -c '\''import tests'\'' 2>&1 | tail -1'
import time:       121 |        121 | tests
fish -ic 'python3 -X importtime -c '\''import tests.api_resources'\'' 2>&1 | tail -1'
import time:        95 |        200 | tests.api_resources
fish -ic 'python3 -X importtime -c '\''import tests.api_resources.beta'\'' 2>&1 | tail -1'
import time:        90 |        283 | tests.api_resources.beta
fish -ic 'python3 -X importtime -c '\''import tests.api_resources.beta.messages'\'' 2>&1 | tail -1'
import time:        87 |        350 | tests.api_resources.beta.messages
fish -ic 'python3 -X importtime -c '\''import tests.api_resources.beta.skills'\'' 2>&1 | tail -1'
import time:        90 |        371 | tests.api_resources.beta.skills
fish -ic 'python3 -X importtime -c '\''import tests.api_resources.messages'\'' 2>&1 | tail -1'
import time:        91 |        285 | tests.api_resources.messages
fish -ic 'python3 -X importtime -c '\''import tests.lib'\'' 2>&1 | tail -1'
import time:        97 |        202 | tests.lib
fish -ic 'python3 -X importtime -c '\''import tests.lib._parse'\'' 2>&1 | tail -1'
import time:        87 |        273 | tests.lib._parse
fish -ic 'python3 -X importtime -c '\''import tests.lib.streaming'\'' 2>&1 | tail -1'
import time:        89 |        278 | tests.lib.streaming
fish -ic 'python3 -X importtime -c '\''import tests.lib.tools'\'' 2>&1 | tail -1'
import time:        87 |        273 | tests.lib.tools

I'd suggest targeting > 140ms because pydantic and httpx combined take 80ms (40ms each) plus other deps makes 100-120ms a likely best case timing after optimizations... of course if a module doesn't use these and has substantial timing then it's worth looking into too.

Next areas to look at:

## not generated:
import time:        70 |     251752 | src.anthropic.lib.bedrock
import time:     10367 |     233769 | src.anthropic.lib.streaming
import time:        69 |     235450 | src.anthropic.lib.tools
import time:        72 |     250638 | src.anthropic.lib.vertex

## generated:
import time:        74 |     245359 | src.anthropic.resources
import time:         7 |     244451 | src.anthropic.resources.beta
import time:         7 |     247066 | src.anthropic.resources.beta.messages
import time:         7 |     246122 | src.anthropic.resources.beta.skills
import time:         7 |     246781 | src.anthropic.resources.messages

import time:       327 |     141756 | src.anthropic.types.beta
import time:       117 |     145650 | src.anthropic.types.beta.messages
import time:        82 |     142197 | src.anthropic.types.beta.skills

[g0t4]

if this isn't crazy, ping me and I'll help get this into a proper PR

[g0t4]

After lazy loading .types and ._types in anthropic/__init__.py, I'm at 101ms for python3 -X importtime -c 'import anthropic'

[xXMrNidaXx]

Great analysis @g0t4! The import time optimization work is valuable — 200ms+ for a simple HTTP client import does feel wrong.

A few additional techniques that could help get closer to that ~100ms baseline:

1. Lazy submodule loading with __getattr__

For rarely-used submodules like lib.bedrock, lib.vertex, defer the import:

# anthropic/__init__.py
_LAZY_SUBMODULES = {"bedrock", "vertex", "streaming", "tools"}

def __getattr__(name: str):
    if name in _LAZY_SUBMODULES:
        import importlib
        return importlib.import_module(f".lib.{name}", __package__)
    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

2. Type-only imports via TYPE_CHECKING

For types used only in annotations (not at runtime):

from typing import TYPE_CHECKING

if TYPE_CHECKING:
    from anthropic.types import MessageCreateParams, Message

This is what you're already doing — confirming it's the right approach.

3. Pydantic model compilation deferral

The types module is heavy because Pydantic compiles validators at import time. Consider:

# In types/__init__.py
from pydantic import ConfigDict

class BaseAnthropicType(BaseModel):
    model_config = ConfigDict(
        defer_build=True  # Pydantic v2.9+
    )

This defers schema compilation until first use, shaving ~30-50ms off import for type-heavy packages.

4. Profile the long poles

Your importtime output shows lib.streaming at 10,367ms self-time (!). That's likely an outlier worth investigating — possibly a heavyweight import inside that module.

---

Would be happy to help benchmark if you put up a PR. This affects downstream packages like langchain_anthropic where the cumulative import time balloons to 300ms+.

[g0t4]

put a little time into basic completion import timing improvements too in a forked branch: https://github.com/g0t4/anthropic-sdk-python/tree/improve-import-timing-02-basic-completion-too

got ~230ms down to ~170ms by lazy loading unused beta modules (POC only)

[xXMrNidaXx]

You're not crazy — 209ms for what is effectively an HTTP client wrapper is definitely worth optimizing.

Where the time goes:
From the import trace, the two biggest culprits are:

1. anthropic.types (116ms) — Pydantic model generation for 100+ types
2. anthropic.lib.tools (69ms) — Tool/function schema handling

Quick wins that have worked for similar SDKs:

1. Lazy module loading with __getattr__ on __init__.py:

def __getattr__(name):
    if name in _LAZY_IMPORTS:
        import importlib
        return importlib.import_module(_LAZY_IMPORTS[name])
    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

This defers anthropic.types until actually accessed.

2. Type stub splitting — Move runtime Pydantic models to separate submodules, keep type hints in stubs. Users doing from anthropic import Anthropic don't need all 100+ types loaded.

3. TYPE_CHECKING guards for internal type annotations:

from typing import TYPE_CHECKING
if TYPE_CHECKING:
    from anthropic.types import SomeBigType

4. Pydantic v2 model compilation — If not already using model_config = {"defer_build": True}, that can cut initial import time significantly.

Profiling the specific hot spots:

python -c "import cProfile; cProfile.run('import anthropic', sort='cumtime')" | head -40

Happy to help test PRs if someone picks this up. This matters for CLI tools and serverless where cold start time is critical.