Environment:Groq Groq python Python Groq SDK

Knowledge Sources	Groq Python SDK PyPI groq
Domains	API_Client, Infrastructure
Last Updated	2026-02-15 17:00 GMT

Overview

Python 3.9+ environment with the groq SDK package (v1.0.0) and its core dependencies (httpx, pydantic, anyio) for accessing the Groq cloud inference API.

Description

This environment provides the runtime context for all Groq Python SDK operations. It is a pure Python package with no native compilation or GPU requirements. The SDK is built on httpx for HTTP transport, pydantic for response model validation (supporting both v1 and v2), anyio for async I/O abstraction, and typing-extensions for backported type features. An optional aiohttp extra is available for improved async concurrency performance.

The SDK is cross-platform and runs on Linux, macOS, Windows, FreeBSD, and OpenBSD. It is generated by Stainless from the Groq OpenAPI specification, with all API endpoints prefixed under /openai/v1/.

Usage

This environment is required by every Groq SDK implementation. Any workflow that calls the Groq API (chat completions, audio transcription, text-to-speech, batch processing, embeddings) requires this environment to be set up first.

System Requirements

Category	Requirement	Notes
OS	Linux, macOS, Windows	Also supports FreeBSD, OpenBSD; cross-platform
Python	>= 3.9	Tested on 3.9, 3.10, 3.11, 3.12, 3.13, 3.14
Hardware	Standard CPU	No GPU required; pure API client
Network	Internet access	Must reach https://api.groq.com (or custom base URL)

Dependencies

Python Packages (Core)

groq >= 1.0.0
httpx >= 0.23.0, < 1
pydantic >= 1.9.0, < 3
typing-extensions >= 4.10, < 5
anyio >= 3.5.0, < 5
distro >= 1.7.0, < 2
sniffio

Python Packages (Optional)

aiohttp (for improved async concurrency)
httpx_aiohttp >= 0.1.9 (aiohttp transport adapter)

Credentials

The following environment variables must be configured:

GROQ_API_KEY: Required. Groq API key for authentication. Obtain from https://console.groq.com. Can also be passed directly via the api_key constructor parameter.
GROQ_BASE_URL: Optional. Override the default API base URL (default: https://api.groq.com). Useful for proxies or testing.
GROQ_LOG: Optional. Set to "debug" or "info" to enable SDK and httpx logging output.

Quick Install

# Install core SDK
pip install groq

# For improved async performance (optional)
pip install "groq[aiohttp]"

Code Evidence

Python version requirement from pyproject.toml:20:

requires-python = ">= 3.9"

API key resolution from src/groq/_client.py:76-81:

if api_key is None:
    api_key = os.environ.get("GROQ_API_KEY")
if api_key is None:
    raise GroqError(
        "The api_key client option must be set either by passing api_key to the client or by setting the GROQ_API_KEY environment variable"
    )

Base URL resolution from src/groq/_client.py:84-87:

if base_url is None:
    base_url = os.environ.get("GROQ_BASE_URL")
if base_url is None:
    base_url = f"https://api.groq.com"

Logging setup from src/groq/_utils/_logs.py:16-25:

def setup_logging() -> None:
    env = os.environ.get("GROQ_LOG")
    if env == "debug":
        _basic_config()
        logger.setLevel(logging.DEBUG)
        httpx_logger.setLevel(logging.DEBUG)
    elif env == "info":
        _basic_config()
        logger.setLevel(logging.INFO)
        httpx_logger.setLevel(logging.INFO)

Core dependencies from pyproject.toml:11-18:

dependencies = [
  "httpx>=0.23.0, <1",
  "pydantic>=1.9.0, <3",
  "typing-extensions>=4.10, <5",
  "anyio>=3.5.0, <5",
  "distro>=1.7.0, <2",
  "sniffio",
]

Optional aiohttp dependency handling from src/groq/_base_client.py:1305-1320:

try:
    import httpx_aiohttp
except ImportError:
    class _DefaultAioHttpClient(httpx.AsyncClient):
        def __init__(self, **_kwargs: Any) -> None:
            raise RuntimeError(
                "To use the aiohttp client you must have installed the package with the `aiohttp` extra"
            )

Common Errors

Error Message	Cause	Solution
`GroqError: The api_key client option must be set...`	No API key provided	Set `GROQ_API_KEY` env var or pass `api_key=` to constructor
`RuntimeError: To use the aiohttp client you must have installed...`	aiohttp extra not installed	Run `pip install "groq[aiohttp]"`
`ImportError: No module named 'groq'`	SDK not installed	Run `pip install groq`
`AuthenticationError` (401)	Invalid API key	Verify your API key at https://console.groq.com

Compatibility Notes

Pydantic v1 and v2: The SDK supports both Pydantic v1 (>= 1.9.0) and v2 (< 3) through an internal compatibility layer in src/groq/_compat.py.
Python 3.9: Minimum supported version. Some internal type handling differs for Python < 3.10 and < 3.12.
Async runtimes: The SDK uses anyio for async abstraction. asyncio is the primary supported runtime; other runtimes (e.g., trio) have limited support.
httpx versions: Supports httpx >= 0.23.0 but < 1.0. The SDK sets custom defaults (timeout, connection limits, redirect following) that differ from httpx defaults.

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment