Installation & Setup

Getting started with the Tavily Python SDK takes only a few minutes. This guide covers standard installation, optional dependencies for advanced features, and best practices for managing your API keys securely.

System Requirements

  • Python Version: Python 3.8 or higher is strictly required.
  • Operating System: OS Independent (Windows, macOS, Linux).

Standard Installation

The recommended way to install the Tavily Python wrapper is via pip. We highly suggest installing this within a virtual environment (like venv, conda, or poetry) to prevent dependency conflicts.

# Upgrade pip to ensure a smooth installation
python -m pip install --upgrade pip

# Install the Tavily SDK
pip install tavily-python

What gets installed?

By default, installing tavily-python brings in three lightweight, crucial dependencies:

  1. requests: Powers the synchronous TavilyClient.
  2. httpx: Powers the non-blocking AsyncTavilyClient.
  3. tiktoken (>=0.5.1): Used internally by the SDK to accurately calculate token lengths (based on OpenAI's encoding), ensuring context generation doesn't overflow your LLM's context window.

Optional Dependencies for Hybrid RAG

If you intend to use the Hybrid RAG capabilities (combining your local database with Tavily's web search), you will need to install specific drivers. Currently, TavilyHybridClient supports MongoDB and utilizes Cohere for embeddings and reranking by default.

# Install optional dependencies for Hybrid RAG
pip install pymongo cohere

Note: You only need these if you are actively importing and using tavily.hybrid_rag.TavilyHybridClient.

Authentication & API Keys

To interact with the Tavily API, you must authenticate using a valid API key.

  1. Navigate to the Tavily Platform and create an account.
  2. Generate a new API key from your dashboard. It will look something like tvly-XXXXXXXXXXXXXX.

Best Practice: Environment Variables

Hardcoding API keys in your source code is a major security risk. The SDK is designed to automatically detect your API key if it is stored in the TAVILY_API_KEY environment variable.

On macOS/Linux: 

export TAVILY_API_KEY="tvly-YOUR_API_KEY"

On Windows (Command Prompt): 

set TAVILY_API_KEY="tvly-YOUR_API_KEY"

Using .env files (Recommended for local development): If you use a package like python-dotenv, create a .env file in your project root: 

TAVILY_API_KEY=tvly-YOUR_API_KEY

Load it in your Python script before initializing the client: 

from dotenv import load_dotenv
from tavily import TavilyClient

load_dotenv() # Loads variables from .env into the environment
client = TavilyClient() # Automatically picks up TAVILY_API_KEY

Troubleshooting Common Installation Issues

  • MissingAPIKeyError on Startup: If you initialize TavilyClient() and receive this error, the SDK cannot find your environment variable. Ensure it is exported in the exact terminal session where you are running your script, or pass it directly via TavilyClient(api_key="...").
  • Dependency Conflicts: If you encounter issues with httpx or requests versions clashing with other libraries in your project, ensure you are using a dedicated virtual environment.
  • Legacy Imports: Ensure you are using the modern import structure from tavily import TavilyClient. The older from tavily import Client is deprecated and will trigger warnings.