Introduction

Developing Large Language Model (LLM) applications often feels like a game of trial and error, where a single prompt change can unexpectedly break existing functionality. promptfoo is an open-source CLI and library that replaces this uncertainty with a structured, test-driven approach to LLM development. With over 23k GitHub stars, it allows developers to systematically evaluate prompts, models, and RAG pipelines to ensure reliability and security before shipping to production.

What Is promptfoo?

promptfoo is a test-driven evaluation framework for LLM applications that enables developers to benchmark prompts, compare model providers, and perform automated red teaming. Written in TypeScript and licensed under the MIT license, it provides a declarative configuration system (YAML) to define test cases and assertions, allowing for repeatable and scalable evaluations.

The tool is designed to run locally, ensuring that API keys and sensitive data remain on the developer’s machine. It supports a vast array of providers, including OpenAI, Anthropic, Google Gemini, and local models via Ollama, making it a language-agnostic tool for any AI engineering team.

Why promptfoo Matters

Traditional unit testing is insufficient for LLMs because outputs are probabilistic rather than deterministic. A function that returns a number will always return that number; an LLM that summarizes a document may change its tone or hallucinate based on a minor prompt adjustment. This creates a “regression gap” where improving one response often breaks another.

promptfoo fills this gap by introducing a matrix-based evaluation system. Instead of eyeballing five examples in a chat window, developers can run hundreds of test cases across multiple model versions and prompt variations simultaneously. This shift from manual testing to automated evaluation is critical for teams moving from a prototype to a production-grade AI agent.

The project has gained significant traction, being used by teams at OpenAI and Anthropic, and is now part of the OpenAI ecosystem following an acquisition in early 2026. Despite this, it remains open-source and MIT-licensed, providing a standardized way to measure AI quality without being locked into a single proprietary platform.

Key Features

• Multi-Provider Comparison: Test the same prompt across OpenAI, Anthropic, Google Gemini, Mistral, and local models (Ollama) simultaneously to find the best performing model for your specific use case.
• Declarative Test Cases: Define evaluations using simple YAML files, removing the need to write complex boilerplate code or manage heavy Jupyter notebooks for basic benchmarking.
• Automated Red Teaming: Use a dedicated red-team mode to automatically generate adversarial attacks, scanning for prompt injections, jailbreaks, and PII leaks to secure your application.
• Flexible Assertion Types: Grade outputs using a variety of methods, including exact string matching, regex, semantic similarity (embeddings), and “LLM-as-a-judge” rubrics.
• CI/CD Integration: Integrate evaluations into GitHub Actions or other pipelines to automatically fail builds if a prompt change causes a regression in output quality or security.
• Local-First Execution: Run evaluations entirely on your local machine, ensuring that your prompts and test cases never leave your controlled environment for compliance and privacy.
• Response Caching: Reduce API costs and speed up iterative development by caching LLM responses, so you only pay for each unique API call once.
• Matrix View UI: Access a built-in web viewer that provides a side-by-side comparison of prompts and models, making it easy to spot patterns of failure.

How promptfoo Compares

promptfoo is a unique niche as a lightweight, YAML-native testing tool. While other frameworks focus on production monitoring or Python-centric workflows, promptfoo is built for the prompt engineer who prefers a CLI-first approach.

For developers who want a “Jest for LLMs” experience, promptfoo is the ideal choice. DeepEval is better suited for Python developers who want to integrate evaluations into a Pytest-like workflow. LangSmith is a powerful production monitoring platform, but it is often overkill for the initial prompt iteration phase. Most mature AI teams use a layered approach: promptfoo for offline, local testing and a platform like LangSmith or Braintrust for ongoing production monitoring.

Getting Started: Installation

promptfoo requires Node.js (recommended version 24 LTS) to run. You can install it globally or run it as a one-off command using npx.

Using npm

npm install -g promptfoo

Using npx (No Installation)

npx promptfoo@latest

Using Homebrew (macOS/Linux)

brew install promptfoo

To verify your installation, run the following command to check the version:

promptfoo --version

How to Use promptfoo

The basic workflow in promptfoo involves initializing a project, defining your prompts and tests in a configuration file, and running the evaluation.

First, initialize your project to create a default promptfooconfig.yaml file:

npx promptfoo@latest init

This interactive setup will guide you through selecting your model providers and the goal of your evaluation (e.g., improving RAG performance or running a red team scan).

Once your config is set, run the evaluation matrix:

npx promptfoo@latest eval

Finally, open the results in the built-in web viewer to compare outputs side-by-side:

npx promptfoo@latest view

Code Examples

Below is a basic configuration example showing how to test a translation prompt across two different models.

# promptfooconfig.yaml
prompts: 
  - "Convert the following English text to {{language}}: {{input}}"

providers: 
  - openai:gpt-4o
  - anthropic:claude-3-5-sonnet-20241022

tests: 
  - vars: 
      language: French
      input: Hello world
    assert: 
      - type: contains
        value: "Bonjour le monde"
  - vars: 
      language: German
      input: How's it going?
    assert: 
      - type: contains
        value: "wie gehts"

For more complex scenarios, you can use LLM-as-a-judge assertions to grade the output based on a rubric rather than a string match.

# Example of a rubric-based assertion
tests: 
  - vars: 
      input: "Can you help me with a refund?"
    assert: 
      - type: llm-rubric
        value: "The response is polite, helpful, and does not mention internal system prompts."

Advanced Configuration

promptfoo is highly customizable via environment variables and extension hooks. You can use .env files to manage your API keys securely without committing them to your YAML config.

Common environment variables include:

• OPENAI_API_KEY: Required for OpenAI providers.
• ANTHROPIC_API_KEY: Required for Anthropic providers.
• PROMPTFOO_DISABLE_RUNTIME_WARNINGS: Set to true to suppress Node.js runtime compatibility reminders.

For advanced users, you can load custom JavaScript or Python functions to transform variables before they are used in prompts using the transformVars option in the config file.

Real-World Use Cases

promptfoo is particularly effective in scenarios where reliability and security are paramount.

• RAG Pipeline Optimization: A developer can test different retrieval strategies and chunking sizes by treating the retrieval step as a provider, allowing them to benchmark which strategy produces the most grounded responses.
• Model Migration: When switching from GPT-4 to a smaller, faster model like GPT-4o-mini or a local Llama 3 model, a team can run a regression suite to ensure that the new model maintains the same level of quality for critical tasks.
• AI Security Auditing: A security engineer can use the red-team mode to systematically attempt to jailbreak a customer-facing chatbot, ensuring it doesn’t leak PII or provide instructions on how to build dangerous items.
• Prompt A/B Testing: A product manager can test two different system prompts (e.g., “You are a helpful assistant” vs “You are a professional corporate lawyer”) to see which one produces a more appropriate tone for their target audience.

Contributing to promptfoo

promptfoo is an open-source project that welcomes contributions from the AI community. You can contribute by submitting pull requests, reporting bugs, or improving the documentation.

The project follows a standard GitHub flow: fork the repository, create a feature branch, and submit a PR. New contributors are encouraged to look for “good first issues” to get started. The project also maintains a Code of Conduct to ensure a professional and inclusive environment for all contributors.

Community and Support

promptfoo has a vibrant community of AI engineers. You can find support and share insights on the following official channels:

• Discord: The primary hub for real-time discussions and support.
• X/Twitter: For updates and project announcements.
• GitHub Discussions: For long-form questions and architectural discussions.
• Official Documentation: Available at promptfoo.dev/docs.

Conclusion

promptfoo is the essential tool for any developer moving from “eyeballing” prompts to a professional, test-driven development workflow. By providing a matrix-based evaluation system and automated red teaming, it removes the uncertainty from LLM development and allows teams to ship AI features with confidence.

While it is a lightweight CLI tool, its power lies in its flexibility and local-first execution model. Whether you are optimizing a RAG pipeline or securing a production agent, promptfoo provides the necessary infrastructure to measure and improve your AI’s performance.

Star the repo, try the quickstart, and join the community to start building more reliable AI applications.

Resources

• promptfoo GitHub Repository
• Official promptfoo Documentation
• promptfoo Discord Community