Install & Compatibility
Where this runs
tested against v0.1.26 · 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 3.190s · 67.4MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 8.9s · import 2.936s · 69MB
68MB installed
● package 68MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
calculate_prompt_cost
✓ from tokencost import calculate_prompt_cost
calculate_completion_cost
✓ from tokencost import calculate_completion_cost
This quickstart demonstrates how to calculate the estimated token cost for both a prompt and its completion using `tokencost`. It includes an optional interaction with the OpenAI API for a realistic example, which requires the `OPENAI_API_KEY` environment variable to be set. The library automatically handles different tokenization methods for various LLM providers.
import os
from openai import OpenAI
from tokencost import calculate_prompt_cost, calculate_completion_cost
# Ensure OPENAI_API_KEY is set in your environment variables
openai_api_key = os.environ.get('OPENAI_API_KEY', 'YOUR_OPENAI_API_KEY')
if not openai_api_key or openai_api_key == 'YOUR_OPENAI_API_KEY':
print("Warning: OPENAI_API_KEY environment variable not set. Using dummy key.")
# This allows the example to run without an actual API call, but cost calculation still works.
# For actual API calls, replace with a valid key or set the env var.
client = OpenAI(api_key=openai_api_key)
model = "gpt-3.5-turbo"
prompt_messages = [{ "role": "user", "content": "Say this is a test"}]
# Simulate an OpenAI API call (or make a real one if API key is valid)
try:
chat_completion = client.chat.completions.create(
messages=prompt_messages,
model=model
)
completion_content = chat_completion.choices[0].message.content
print(f"API Completion: {completion_content}")
except Exception as e:
print(f"Could not make actual OpenAI API call (continuing with dummy completion for cost calculation): {e}")
completion_content = "This is a test."
# Calculate costs
prompt_cost = calculate_prompt_cost(prompt_messages, model)
completion_cost = calculate_completion_cost(completion_content, model)
total_cost = prompt_cost + completion_cost
print(f"Prompt Cost: ${prompt_cost:.6f}")
print(f"Completion Cost: ${completion_cost:.6f}")
print(f"Total Estimated Cost: ${total_cost:.6f}")
Debug
Known issues
gotchaLLM providers frequently update model pricing and introduce new models. To ensure accurate cost estimations, it is crucial to keep the `tokencost` library updated to its latest version.fixRegularly update the library: `pip install --upgrade tokencost`.
affects: All versions
gotchaDifferent LLM providers (e.g., OpenAI, Anthropic) use distinct tokenization methods. Manual token counting or cost estimation can be inaccurate due to these variations (e.g., Tiktoken for OpenAI, Anthropic's beta API for Claude 3.5+). `tokencost` abstracts this complexity, using the appropriate tokenizer for each model.fixAlways use `tokencost` for reliable, model-specific token counting and cost estimation instead of attempting manual calculations or generic tokenizers.
affects: All versions
gotchaSome advanced LLMs generate 'reasoning tokens' (internal thought processes) that are billed at the more expensive output token rate but are not visible in the final API response. This can lead to higher-than-expected costs for a given visible output. `tokencost` helps in understanding the total cost incurred by such models.fixMonitor total costs reported by `tokencost` and consider using more cost-efficient models or prompt engineering strategies to reduce internal reasoning if costs are a concern.
affects: Models with internal reasoning capabilities (e.g., GPT-4, Claude Opus)
breakingPast versions (e.g., 0.1.20) had fixes for incorrect token and cost calculations for certain OpenAI 'o' series models and issues with lazy loading of `update_token_costs`. While addressed, this highlights the dynamic nature of LLM pricing and tokenization.fixEnsure you are on `tokencost` version 0.1.20 or newer to benefit from these specific fixes. Always keep the library updated to receive the latest pricing and tokenization logic corrections.
affects: <=0.1.19
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'tokencost'
The tokencost library has not been installed in your current Python environment.
KeyError: 'invalid_model_name'
The provided model name is either misspelled or not supported by the tokencost library.
fixConsult the tokencost documentation or available model list to use a correct and valid model name (e.g., 'gpt-4', 'claude-3-opus-20240229').
TypeError: expected string or bytes-like object, got list
The 'text' argument passed to tokencost.count_tokens or tokencost.estimate_cost is not a string.
fixEnsure the 'text' argument is a single string; if you have multiple texts, process them individually or concatenate them into a single string.
Upgrade
Version history
0.1.26latest on PyPI · released Aug 13, 2025
Audit
Dependencies
openaioptionalUsed in common quickstart examples for actual API calls, though not a direct installation dependency of tokencost itself.