Install & Compatibility
Where this runs
tested against v0.11.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.915 runs
installs and imports cleanly · install 0.0s · import 1.541s · 80.1MB
glibcpy 3.10–3.915 runs
installs and imports cleanly · install 7.5s · import 1.428s · 89MB
84MB installed
● package 84MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
traceable
✓ from langsmith import traceable
Primary decorator for instrumenting any function. Works standalone — does not require LangChain.
wrap_openai
✓ from langsmith.wrappers import wrap_openai
Wraps an OpenAI client to auto-trace all calls. Equivalent wrappers exist for Anthropic (wrap_anthropic).
Client
✓ from langsmith import Client
Low-level client for dataset management, run querying, and evaluation APIs.
Env vars must be set BEFORE importing LangChain/LangSmith — they are read at import time. Setting them after import has no effect. LANGSMITH_TRACING must be the string 'true', not a boolean.
import os
os.environ['LANGSMITH_TRACING'] = 'true'
os.environ['LANGSMITH_API_KEY'] = 'ls_...'
os.environ['LANGSMITH_PROJECT'] = 'my-project'
# Option 1: Wrap OpenAI client (auto-traces all calls)
import openai
from langsmith.wrappers import wrap_openai
client = wrap_openai(openai.OpenAI())
response = client.chat.completions.create(
model='gpt-4o',
messages=[{'role': 'user', 'content': 'Hello!'}]
)
# Option 2: @traceable decorator for arbitrary functions
from langsmith import traceable
@traceable
def my_pipeline(query: str) -> str:
# any code here is traced as a span
response = client.chat.completions.create(
model='gpt-4o',
messages=[{'role': 'user', 'content': query}]
)
return response.choices[0].message.content
result = my_pipeline('What is 2+2?')
# Option 3: LangChain auto-tracing (no decorator needed)
# Just set env vars — all LangChain/LangGraph calls are traced automatically
from langchain_openai import ChatOpenAI
llm = ChatOpenAI(model='gpt-4o')
llm.invoke('Hello!') # automatically traced
Debug
Known issues
breakingCVE-2026-25528: SSRF via baggage header injection. The distributed tracing feature is vulnerable — attackers can inject arbitrary api_url values via the baggage HTTP header, causing the SDK to exfiltrate trace data to attacker-controlled endpoints. Affects versions 0.4.10–0.6.2.fixUpgrade immediately: pip install 'langsmith>=0.6.3'. Do not run affected versions in environments that process untrusted HTTP requests.
affects: >=0.4.10,<0.6.3
breakingLANGCHAIN_TRACING_V2 and LANGCHAIN_API_KEY are the legacy env var names. Current docs use LANGSMITH_TRACING and LANGSMITH_API_KEY. Both still work, but mixing old and new names in the same environment causes confusing precedence issues.fixStandardize on LANGSMITH_TRACING and LANGSMITH_API_KEY in all new code and CI configs. Remove LANGCHAIN_TRACING_V2 from environments.
affects: all
breakinglangsmith 0.5+ has a strict version conflict with older langchain versions. langchain 0.3.x requires langsmith<0.2.0. Installing langsmith>=0.5 in a langchain 0.3 environment causes a pip resolver conflict that breaks the entire environment.fixUpgrade langchain to the latest version before upgrading langsmith. Or pin both: langchain==0.3.x requires langsmith<0.2.
affects: langsmith>=0.5 with langchain<0.4
gotchaLANGSMITH_TRACING must be set BEFORE LangChain is imported. LangChain reads the env var at import time. Setting os.environ['LANGSMITH_TRACING'] = 'true' after 'from langchain...' has already run produces zero traces with no error.fixSet all LANGSMITH_* env vars at the very top of your entry point, before any LangChain/LangSmith imports. Use .env files loaded via python-dotenv before other imports.
affects: all
gotchaLANGSMITH_TRACING='true' must be a string, not a boolean. In some YAML/env file parsers, setting LANGSMITH_TRACING: true (no quotes) passes the Python boolean True, which the SDK does not recognize. Traces silently drop.fixAlways quote the value: LANGSMITH_TRACING='true' (shell) or LANGSMITH_TRACING: 'true' (YAML).
affects: all
gotchaTraces are sent asynchronously in a background thread. In short-lived scripts, the process may exit before all traces are flushed, resulting in missing or partial traces in the UI.fixCall langsmith.utils.wait_for_all_tracers() at the end of short-lived scripts to ensure all traces are flushed before exit.
affects: all
breakingThe script attempts to import the 'openai' package, but it is not installed in the environment. This error occurs when your application relies on 'openai' without explicitly including it in its dependencies.fixInstall the 'openai' package: `pip install openai`. Ensure all external dependencies required by your application are explicitly listed and installed.
affects: all
Errors
Common errors & fixes
langsmith.utils.LangSmithAuthError: Authentication failed
This error typically occurs due to an incorrect LangSmith API key, using the wrong environment variable name (e.g., LANGSMITH_API_KEY instead of LANGCHAIN_API_KEY), an invalid project name in LANGCHAIN_PROJECT, or insufficient permissions for the API key.
fixEnsure the `LANGCHAIN_API_KEY` environment variable is correctly set with your valid LangSmith API key (it should start with `ls_`). Verify that `LANGCHAIN_PROJECT` matches an existing project name in your LangSmith dashboard and that `LANGCHAIN_TRACING_V2` is set to 'true'. Regenerate your API key on the LangSmith settings page if unsure.
TypeError: Failed to fetch (LangSmith Studio / langgraph dev connection issue)
This issue arises when the LangSmith Studio (an HTTPS site) cannot connect to a local development server (HTTP localhost), primarily due to Chrome versions 142+ enforcing Private Network Access (PNA) specifications or interfering browser extensions.
fixIn Chrome, navigate to `https://smith.langchain.com`, click the lock icon in the address bar, find 'Local network access', and change its setting to 'Allow'. Reload the page. Alternatively, temporarily disable browser extensions (especially AI-related ones) or run `langgraph dev --tunnel` and use the provided tunnel URL in Studio's 'Connect to a local server' option.
No traces appearing in LangSmith UI when using @traceable decorator
Traces might not appear if the tracing environment variables (`LANGCHAIN_TRACING_V2` or `LANGSMITH_TRACING`) are not set to 'true', if the LangSmith API key or endpoint is incorrect, or if the Python process exits before asynchronous traces can be flushed and sent to LangSmith.
fixSet the environment variable `LANGCHAIN_TRACING_V2=true` (or `LANGSMITH_TRACING=true`). Double-check `LANGCHAIN_API_KEY` and `LANGCHAIN_ENDPOINT` for correctness. For short scripts or applications that exit quickly, explicitly call `langsmith.flush_traces()` or `langchain.callbacks.tracers.wait_for_all_tracers()` at the end of your script to ensure traces are sent.
ModuleNotFoundError: No module named 'langsmith'
This indicates that the `langsmith` package, or a specific submodule it depends on, is not installed in the currently active Python environment, or it's not correctly bundled/installed in deployment environments like Docker containers or cloud platforms.
fixInstall the `langsmith` package using `pip install -U langsmith`. If in a virtual environment, ensure it's activated. For deployment, explicitly list `langsmith` in your `requirements.txt` or `pyproject.toml` and verify that your deployment pipeline successfully installs all dependencies.
Upgrade
Version history
0.11.1latest on PyPI · released Aug 19, 2026
Audit
Dependencies
No dependency data recorded yet.