Install & Compatibility
Where this runs
tested against v1.1.3 · 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 2.374s · 70.5MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 8.0s · import 2.212s · 79MB
73MB installed
● package 73MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
ChatGroq
✓ from langchain_groq import ChatGroq
Used to interact with Groq's chat models for fast inference.
This quickstart demonstrates how to initialize and use the `ChatGroq` model within LangChain. It shows both a single `invoke` call and streaming capabilities. Ensure your `GROQ_API_KEY` is set as an environment variable.
import os
from langchain_groq import ChatGroq
from langchain_core.messages import HumanMessage, SystemMessage
# Ensure your Groq API key is set as an environment variable
# os.environ["GROQ_API_KEY"] = "your_groq_api_key_here"
# Or pass it directly to the ChatGroq constructor (not recommended for production)
groq_api_key = os.environ.get("GROQ_API_KEY")
if not groq_api_key:
print("Error: GROQ_API_KEY environment variable not set.")
else:
llm = ChatGroq(
model="llama-3.3-70b-versatile",
temperature=0.0,
max_retries=2,
api_key=groq_api_key
)
messages = [
SystemMessage(content="You are a helpful assistant that translates English to French."),
HumanMessage(content="I love programming."),
]
# Invoke the model
response = llm.invoke(messages)
print("\n--- Invoke Response ---")
print(f"Content: {response.content}")
# Stream the response
print("\n--- Streaming Response ---")
for chunk in llm.stream(messages):
print(chunk.content, end="")
print()
Debug
Known issues
gotchaThe `GROQ_API_KEY` environment variable must be set for authentication with the Groq API. Failure to do so will result in authentication errors.fixSet `GROQ_API_KEY` in your environment or pass it explicitly to the `ChatGroq` constructor (e.g., `ChatGroq(api_key=...)`).
affects: All versions
gotchaUsing an unsupported or incorrect `model` name when initializing `ChatGroq` will lead to runtime errors. Additionally, certain features like `reasoning_format` or vision input require specific Groq models.fixRefer to the official Groq documentation for a list of available models and their supported capabilities. Common models include 'llama-3.3-70b-versatile' and 'mixtral-8x7b-32768'.
affects: All versions
breakingAs a LangChain partner package, `langchain-groq` relies on `langchain-core`. The LangChain v1.0 update introduced significant breaking changes to `langchain-core`'s API, including changes to import paths, agent initialization, and the universal `Runnable` interface. Old patterns from `langchain` v0.x will not work.fixConsult the official LangChain v1.0 upgrade guide. Update import statements (e.g., `from langchain_core.prompts import ChatPromptTemplate`), use the `invoke` method consistently, and adopt the `Runnable` interface for chains and agents.
affects: Users upgrading from `langchain` v0.x to `langchain-groq` with `langchain-core` v1.x and higher.
gotchaIf utilizing vision capabilities with supported Groq models, ensure that image URLs provided are publicly accessible, return the image directly without redirects, and do not exceed 20MB in size.fixVerify image URL accessibility and size constraints according to Groq API specifications.
affects: All versions supporting vision models
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'langchain_groq'
The `langchain-groq` package is not installed in your current Python environment or there's a typo in the import statement.
fixInstall the package using pip: `pip install langchain-groq` or ensure your IDE/environment is using the correct Python interpreter where it is installed.
AuthenticationError: Error code: 401 - {'error': {'message': 'Invalid API Key'}}
Your Groq API key is either missing, incorrect, expired, or not properly configured as an environment variable (`GROQ_API_KEY`) or passed directly to `ChatGroq`. Sometimes this error can also appear if other LangChain components implicitly try to use an OpenAI API key while Groq is intended.
fixSet your Groq API key as an environment variable: `export GROQ_API_KEY="your_groq_api_key_here"` (replace with your actual key), or pass it directly when initializing ChatGroq: `ChatGroq(api_key="your_groq_api_key")`. Ensure you are using a valid Groq API key, not an OpenAI key if not intended.
Error code: 429 - {'error': {'message': 'Rate limit reached for model `llama3-8b-8192` in organization `org_******` on tokens per minute (TPM): Limit 30000, Used 30640, Requested 560. Please try again in 2.401s. Visit https://console.groq.com/docs/rate-limits for more information.', 'type': 'tokens', 'code': 'rate_limit_exceeded'}}
You have exceeded the rate limits imposed by the Groq API for your account or the specific model you are using.
fixReduce the frequency of your API calls, implement retry logic with exponential backoff, or check your Groq console for current rate limits and consider upgrading your plan if sustained higher usage is needed.
AttributeError: partially initialized module 'groq' has no attribute 'Groq' (most likely due to a circular import)
You likely have a Python file named `groq.py` in your project directory, which conflicts with the actual `groq` library that `langchain-groq` depends on, causing a circular import.
fixRename your local `groq.py` file to something else (e.g., `my_groq_utils.py`) to avoid name collision with the installed `groq` package.
ValueError: Groq does not currently support tool_choice='any'. Should be one of 'auto', 'none', or the name of the tool to call.
The `langchain-groq` integration for Groq's models does not support `tool_choice='any'` when binding tools, which is a feature available in some other LLM integrations like OpenAI.
fixModify your `tool_choice` parameter to either `'auto'`, `'none'`, or specify the exact `name` of the tool you want the model to call.
Upgrade
Version history
1.1.3latest on PyPI · released Jun 10, 2026
Audit
Dependencies
langchain-corerequiredRequired for core LangChain functionalities and abstractions.
groqrequiredThe official Groq Python SDK for API communication.