---
id: openai-harmony
version: "0.0.8"
license: unclear
license_treatment: unclear
maintenance: aging
---

# openai-harmony — OpenAI's response format for its open-weight model series gpt-oss

License: unclear · Maintenance: aging · Downloads: 7.2M/mo

## What it is and what it does

OpenAI Harmony is a Python library that encodes and decodes conversations in the Harmony response format, a structured format designed for OpenAI's open-weight gpt-oss models. The format enables models to output to multiple channels (analysis, commentary, final), handle chain-of-thought reasoning, and structure function calls with tool namespaces. The library wraps a Rust core via PyO3 bindings for performance, exposing a pure-Python API with dataclasses and helper functions.

You use it when building inference solutions that directly invoke gpt-oss models and need to format prompts and parse responses according to the Harmony specification. If you're using gpt-oss through an API provider (HuggingFace, Ollama, vLLM), the provider handles formatting and you don't need this library. The library depends only on Pydantic and aims to keep token sequences loss-free during rendering and parsing.

Use it for:

- Format multi-turn conversations with system, developer, and user roles for direct gpt-oss inference.
- Parse structured model outputs including reasoning, commentary, and function calls from gpt-oss completions.
- Define tool namespaces and function signatures in a format gpt-oss expects for reliable tool calling.
- Encode conversations for token counting and prompt optimization before sending to a gpt-oss model.
- Build a custom inference pipeline that requires explicit control over prompt and response formatting.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Renders and parses the Harmony response format used by OpenAI's gpt-oss models, enabling structured conversation handling, reasoning output, and function calls in Python.

Yes, if you are building a custom inference solution directly using gpt-oss models and need to handle the Harmony format yourself. No, if you are using gpt-oss through a managed API or inference provider—they handle formatting transparently. Caution: the package is aging (282 days since last release) and license terms are unclear; verify both before committing to production use.

## Install

pip install openai-harmony
uv add openai-harmony
poetry add openai-harmony

## Installing openai-harmony

Before you install: Medium install friction due to compiled Rust bindings; prebuilt wheels cover common platforms (x86_64, ARM, i686, ppc64le on Linux/macOS/Windows). Package is aging—last release was 282 days ago—so expect limited active maintenance.

License in practice: License status is unclear; no SPDX identifier or raw license text is available in the metadata. Verify the actual license terms before using in proprietary or restricted contexts.

Quickstart:

pip install openai-harmony

from openai_harmony import (
    load_harmony_encoding,
    HarmonyEncodingName,
    Role,
    Message,
    Conversation,
    SystemContent,
)

enc = load_harmony_encoding(HarmonyEncodingName.HARMONY_GPT_OSS)
convo = Conversation.from_messages([
    Message.from_role_and_content(Role.SYSTEM, SystemContent.new()),
    Message.from_role_and_content(Role.USER, "Hello"),
])
tokens = enc.render_conversation_for_completion(convo, Role.ASSISTANT)

Requires Python ≥3.8; compiled Rust extension must be available for your platform (wheels provided for common architectures).

Verify before relying:

- Whether the package is actively maintained or in maintenance-only mode (282 days since last release, status marked 'aging').
- Actual license terms and any restrictions on commercial or derivative use.
- Whether the harmony format is stable or subject to breaking changes in future gpt-oss model releases.

## Package facts

- License: not declared (unclear)
- Python support: supports_current
- Install friction: medium
- Maintenance: aging
- Downloads: 7.2M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

gpt-oss harmony format, openai response format parsing, structured conversation encoding, function call formatting, chain of thought rendering, llm prompt formatting, harmony tokenization, llm-inference, prompt-formatting, rust-binding

[View on SkillFed](https://skillfed.io/packages/openai-harmony) · [View on PyPI](https://pypi.org/project/openai-harmony/)