Install & Compatibility
Where this runs
tested against v0.8.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.95 runs
installs and imports cleanly · install 0.0s · import 0.568s · 31MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 3.4s · import 0.516s · 32MB
30MB installed
● package 30MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
TavilyClient
✓ from tavily import TavilyClient
Use this for synchronous API calls.
AsyncTavilyClient
✓ from tavily import AsyncTavilyClient
Use this for asynchronous API calls.
MissingAPIKeyError
✓ from tavily import MissingAPIKeyError
Import for handling specific API key related exceptions.
This quickstart initializes the TavilyClient with an API key from an environment variable and performs a basic search query. It includes a check to ensure the API key is provided, which is crucial for successful API calls.
import os
from tavily import TavilyClient
tavily_client = TavilyClient(api_key=os.environ.get('TAVILY_API_KEY', ''))
if not tavily_client.api_key:
raise ValueError("TAVILY_API_KEY environment variable not set. Get your key from tavily.com.")
response = tavily_client.search("What is the capital of France?")
print(response)
Debug
Known issues
deprecatedThe `langchain_community.tools.tavily_search.tool` has been deprecated in favor of the new `langchain-tavily` Python package. This new package supports Search, Extract, Map, and Crawl functionality and receives continuous updates.fixMigrate to `langchain-tavily` by installing `pip install -U langchain-tavily` and updating your LangChain integrations.
affects: All versions when using `langchain_community.tools`
gotchaFailure to provide a valid Tavily API key during client instantiation will result in a `tavily.MissingAPIKeyError`. The API key is essential for all API interactions.fixEnsure `api_key` is passed to `TavilyClient` or `AsyncTavilyClient` constructor, preferably via an environment variable (e.g., `TAVILY_API_KEY`).
affects: All versions
gotchaIntermittent HTTP 400 Client Errors or 500 Server Errors have been reported by users, often related to API outages or invalid/expired API keys.fixRegenerate your API key on the Tavily platform dashboard and retry. Check the Tavily status page or community for service announcements.
affects: All versions (API service-dependent)
gotchaUsing `auto_parameters=True` in the `search` method might automatically set `search_depth` to `advanced`, which can consume more API credits (2 API credits instead of 1 for `basic`).fixTo avoid unexpected costs, explicitly set `search_depth='basic'` or monitor credit usage when `auto_parameters` is enabled.
affects: Versions with `auto_parameters` feature (from ~July 2025 onwards)
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'tavily'
The 'tavily-python' library has not been installed in the active Python environment.
fixpip install tavily-python
Invalid API key, please provide a valid Tavily API key.
The provided Tavily API key is either missing, incorrect, or not accessible via environment variables or direct instantiation.
fixSet the TAVILY_API_KEY environment variable with your valid key, or pass api_key="YOUR_TAVILY_API_KEY" directly when initializing TavilyClient or AsyncTavilyClient.
AttributeError: 'coroutine' object has no attribute 'results'
When using the AsyncTavilyClient, an async method like 'search' was called but not awaited, causing a coroutine object to be returned instead of the actual results.
fixEnsure that calls to async methods like client.search() are prefixed with 'await' within an async function, e.g., 'await client.search(query="...")'.
TavilyApiException: Search timed out.
The Tavily API request exceeded the allowed time limit for the search operation to complete.
fixTry simplifying the search query, retrying the request, or explicitly setting a longer 'timeout' parameter when calling the 'search' method.
Upgrade
Version history
0.8.0latest on PyPI · released Aug 24, 2026
Audit
Dependencies
requestsrequiredUsed for HTTP requests in the synchronous client.
tiktokenrequiredUsed for tokenization, likely for cost estimation or context management.
httpxrequiredUsed for HTTP requests in the asynchronous client.