Install & Compatibility
Where this runs
tested against v0.26.0 · 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.920 runs
installs and imports cleanly · install 0.0s · import 4.306s · 100.5MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 15.1s · import 3.818s · 101MB
194MB installed
● package 194MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
langwatch
✓ import langwatch
setup
✓ langwatch.setup()
Initializes the LangWatch client.
trace
✓ @langwatch.trace()
Decorator to capture an end-to-end operation as a trace.
span
✓ @langwatch.span()
Decorator to instrument specific parts of a pipeline within a trace.
OpenAIInstrumentor
✓ from langwatch.instrumentors import OpenAIInstrumentor
✗ from langwatch import OpenAIInstrumentor
Instrumentors are typically found in the `langwatch.instrumentors` submodule.
LangChainTracer
✓ import langwatch.langchain
langWatchCallback = langwatch.langchain.LangChainTracer()
✗ from langwatch import LangChainTracer
LangChain integration is via `langwatch.langchain` submodule and uses a context manager or callback.
This quickstart demonstrates how to initialize LangWatch, enable automatic OpenAI instrumentation, and trace an asynchronous function that interacts with the OpenAI API. It highlights the use of `langwatch.setup()` and the `@langwatch.trace()` decorator, along with handling the `LANGWATCH_API_KEY`.
import os
import langwatch
from langwatch.instrumentors import OpenAIInstrumentor
from openai import OpenAI
# Ensure your API key is set as an environment variable or pass it directly
# os.environ["LANGWATCH_API_KEY"] = "YOUR_LANGWATCH_API_KEY"
api_key = os.environ.get("LANGWATCH_API_KEY", "")
if not api_key:
print("Warning: LANGWATCH_API_KEY environment variable not set. Traces will not be sent.")
# For demonstration, we'll proceed but you should set your key.
# In a real application, you might raise an error or configure LangWatch to only log locally.
# Initialize LangWatch early in your application
# Automatically instruments OpenAI calls within the decorated functions
langwatch.setup(
api_key=api_key,
instrumentors=[OpenAIInstrumentor()]
)
client = OpenAI(api_key=os.environ.get("OPENAI_API_KEY", "")) # Assume OpenAI API key is also set
@langwatch.trace(name="UserInteraction")
async def handle_user_query(query: str):
print(f"Processing query: {query}")
try:
response = client.chat.completions.create(
model="gpt-3.5-turbo",
messages=[
{"role": "system", "content": "You are a helpful assistant."},
{"role": "user", "content": query}
]
)
result = response.choices[0].message.content
print(f"Assistant's response: {result}")
return result
except Exception as e:
langwatch.get_current_trace().error(str(e)) # Record error if something goes wrong
print(f"An error occurred: {e}")
raise
async def main():
await handle_user_query("Tell me a fun fact about Python.")
# Ensure traces are flushed before the application exits
await langwatch.shutdown()
import asyncio
asyncio.run(main())
langwatch --version
Errors
Common errors & fixes
No traces appearing in LangWatch dashboard.
The `LANGWATCH_API_KEY` environment variable is likely not set, or the API key passed to `langwatch.setup()` is incorrect or missing.
fixSet your LangWatch API key as an environment variable: `export LANGWATCH_API_KEY="your_api_key"` (Linux/macOS) or `$Env:LANGWATCH_API_KEY="your_api_key"` (PowerShell), or pass it directly: `langwatch.setup(api_key="your_api_key")`.
ImportError: cannot import name 'OpenAIInstrumentor' from 'langwatch'
Specific modules like instrumentors are located within subpackages, not directly under the top-level `langwatch` package.
fixImport the symbol from its correct submodule path, e.g., `from langwatch.instrumentors import OpenAIInstrumentor`.
Error: Trace not found for current context.
Attempting to call `langwatch.get_current_trace().error()` or similar trace-specific methods outside of an active trace context (i.e., not within a `@langwatch.trace()` or `@langwatch.span()` decorated function/context block).
fixEnsure all operations that interact with the current trace are performed within a function or block that is decorated with `@langwatch.trace()` or `@langwatch.span()`.
Upgrade
Version history
0.26.0latest on PyPI · released Jun 12, 2026
Audit
Dependencies
openaioptionalCommonly used with LangWatch for LLM instrumentation, as shown in quickstart examples.
langchainoptionalUsed for automatic instrumentation of LangChain applications.
langwatch-scenariooptionalA separate but related library for agent testing simulations.