{"id":30025804,"url":"https://github.com/openai/gpt-oss","last_synced_at":"2026-10-24T20:03:37.640Z","repository":{"id":308396590,"uuid":"1007222028","full_name":"openai/gpt-oss","owner":"openai","description":"gpt-oss-120b and gpt-oss-20b are two open-weight language models by OpenAI","archived":false,"fork":false,"pushed_at":"2026-10-12T20:24:26.000Z","size":10877,"stargazers_count":20492,"open_issues_count":169,"forks_count":2186,"subscribers_count":128,"default_branch":"main","last_synced_at":"2026-10-24T19:38:45.289Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://openai.com/open-models","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/openai.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"claude":null,"gemini":null,"cursor":null,"copilot":null,"dco":null,"cla":null,"disclosure":null}},"created_at":"2025-06-23T16:43:33.000Z","updated_at":"2026-10-24T18:15:57.000Z","dependencies_parsed_at":"2026-08-30T01:30:19.871Z","dependency_job_id":null,"html_url":"https://github.com/openai/gpt-oss","commit_stats":null,"previous_names":["openai/gpt-oss"],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/openai/gpt-oss","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openai%2Fgpt-oss","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openai%2Fgpt-oss/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openai%2Fgpt-oss/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openai%2Fgpt-oss/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/openai","download_url":"https://codeload.github.com/openai/gpt-oss/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openai%2Fgpt-oss/sbom","scorecard":{"id":1245244,"data":{"date":"2026-03-23","repo":{"name":"github.com/openai/gpt-oss","commit":"443012b24a6fb9aa601c3b82facdbff2a0f79c38"},"scorecard":{"version":"v5.4.1-0.20260322035059-c0df03399ddd","commit":"c0df03399ddd8c3345b62ff3df813f3cbbe5bf42"},"score":5.8,"checks":[{"name":"Maintained","score":3,"reason":"4 commit(s) and 0 issue activity found in the last 90 days -- score normalized to 3","details":null,"documentation":{"short":"Determines if the project is \"actively maintained\".","url":"https://github.com/ossf/scorecard/blob/c0df03399ddd8c3345b62ff3df813f3cbbe5bf42/docs/checks.md#maintained"}},{"name":"Code-Review","score":8,"reason":"Found 24/30 approved changesets -- score normalized to 8","details":null,"documentation":{"short":"Determines if the project requires human code review before pull requests (aka merge requests) are merged.","url":"https://github.com/ossf/scorecard/blob/c0df03399ddd8c3345b62ff3df813f3cbbe5bf42/docs/checks.md#code-review"}},{"name":"Dangerous-Workflow","score":10,"reason":"no dangerous workflow patterns detected","details":null,"documentation":{"short":"Determines if the project's GitHub Action workflows avoid dangerous patterns.","url":"https://github.com/ossf/scorecard/blob/c0df03399ddd8c3345b62ff3df813f3cbbe5bf42/docs/checks.md#dangerous-workflow"}},{"name":"Token-Permissions","score":10,"reason":"GitHub workflow tokens follow principle of least privilege","details":["Info: jobLevel 'contents' permission set to 'read': .github/workflows/CI.yml:26","Info: topLevel 'contents' permission set to 'read': .github/workflows/CI.yml:13","Info: no jobLevel write permissions found"],"documentation":{"short":"Determines if the project's workflows follow the principle of least privilege.","url":"https://github.com/ossf/scorecard/blob/c0df03399ddd8c3345b62ff3df813f3cbbe5bf42/docs/checks.md#token-permissions"}},{"name":"Binary-Artifacts","score":10,"reason":"no binaries found in the repo","details":null,"documentation":{"short":"Determines if the project has generated executable (binary) artifacts in the source repository.","url":"https://github.com/ossf/scorecard/blob/c0df03399ddd8c3345b62ff3df813f3cbbe5bf42/docs/checks.md#binary-artifacts"}},{"name":"CII-Best-Practices","score":0,"reason":"no effort to earn an OpenSSF best practices badge detected","details":null,"documentation":{"short":"Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.","url":"https://github.com/ossf/scorecard/blob/c0df03399ddd8c3345b62ff3df813f3cbbe5bf42/docs/checks.md#cii-best-practices"}},{"name":"Security-Policy","score":0,"reason":"security policy file not detected","details":["Warn: no security policy file detected","Warn: no security file to analyze","Warn: no security file to analyze","Warn: no security file to analyze"],"documentation":{"short":"Determines if the project has published a security policy.","url":"https://github.com/ossf/scorecard/blob/c0df03399ddd8c3345b62ff3df813f3cbbe5bf42/docs/checks.md#security-policy"}},{"name":"Pinned-Dependencies","score":0,"reason":"dependency not pinned by hash detected -- score normalized to 0","details":["Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/CI.yml:31: update your workflow using https://app.stepsecurity.io/secureworkflow/openai/gpt-oss/CI.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/CI.yml:34: update your workflow using https://app.stepsecurity.io/secureworkflow/openai/gpt-oss/CI.yml/main?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/CI.yml:58: update your workflow using https://app.stepsecurity.io/secureworkflow/openai/gpt-oss/CI.yml/main?enable=pin","Warn: pipCommand not pinned by hash: .github/workflows/CI.yml:40","Warn: pipCommand not pinned by hash: .github/workflows/CI.yml:44","Info:   0 out of   2 GitHub-owned GitHubAction dependencies pinned","Info:   0 out of   1 third-party GitHubAction dependencies pinned","Info:   0 out of   2 pipCommand dependencies pinned"],"documentation":{"short":"Determines if the project has declared and pinned the dependencies of its build process.","url":"https://github.com/ossf/scorecard/blob/c0df03399ddd8c3345b62ff3df813f3cbbe5bf42/docs/checks.md#pinned-dependencies"}},{"name":"Fuzzing","score":0,"reason":"project is not fuzzed","details":["Warn: no fuzzer integrations found"],"documentation":{"short":"Determines if the project uses fuzzing.","url":"https://github.com/ossf/scorecard/blob/c0df03399ddd8c3345b62ff3df813f3cbbe5bf42/docs/checks.md#fuzzing"}},{"name":"License","score":10,"reason":"license file detected","details":["Info: project has a license file: LICENSE:0","Info: FSF or OSI recognized license: Apache License 2.0: LICENSE:0"],"documentation":{"short":"Determines if the project has defined a license.","url":"https://github.com/ossf/scorecard/blob/c0df03399ddd8c3345b62ff3df813f3cbbe5bf42/docs/checks.md#license"}},{"name":"Signed-Releases","score":-1,"reason":"no releases found","details":null,"documentation":{"short":"Determines if the project cryptographically signs release artifacts.","url":"https://github.com/ossf/scorecard/blob/c0df03399ddd8c3345b62ff3df813f3cbbe5bf42/docs/checks.md#signed-releases"}},{"name":"Branch-Protection","score":-1,"reason":"internal error: error during branchesHandler.setup: internal error: some github tokens can't read classic branch protection rules: https://github.com/ossf/scorecard-action/blob/main/docs/authentication/fine-grained-auth-token.md","details":null,"documentation":{"short":"Determines if the default and release branches are protected with GitHub's branch protection settings.","url":"https://github.com/ossf/scorecard/blob/c0df03399ddd8c3345b62ff3df813f3cbbe5bf42/docs/checks.md#branch-protection"}},{"name":"Packaging","score":10,"reason":"packaging workflow detected","details":["Info: Project packages its releases by way of GitHub Actions.: .github/workflows/CI.yml:17"],"documentation":{"short":"Determines if the project is published as a package that others can easily download, install, easily update, and uninstall.","url":"https://github.com/ossf/scorecard/blob/c0df03399ddd8c3345b62ff3df813f3cbbe5bf42/docs/checks.md#packaging"}},{"name":"SAST","score":0,"reason":"SAST tool is not run on all commits -- score normalized to 0","details":["Warn: 0 commits out of 26 are checked with a SAST tool"],"documentation":{"short":"Determines if the project uses static code analysis.","url":"https://github.com/ossf/scorecard/blob/c0df03399ddd8c3345b62ff3df813f3cbbe5bf42/docs/checks.md#sast"}}]},"last_synced_at":"2026-03-26T18:53:39.774Z","repository_id":308396590,"created_at":"2026-03-26T18:53:39.774Z","updated_at":"2026-03-26T18:53:39.774Z"},"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":345237552,"owners_count":38493951,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-10-03T21:59:58.778Z","status":"online","status_checked_at":"2026-10-24T02:00:07.043Z","response_time":103,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-08-06T09:02:05.436Z","updated_at":"2026-10-24T20:03:37.611Z","avatar_url":"https://github.com/openai.png","language":"Python","funding_links":[],"categories":["Python","Other","others","AI","2. Model Codebases \u0026 Model Families","Models \u0026 robotics","NLP","Health AI \u0026 Machine Learning","Project List","AI models"],"sub_categories":["Scientific Computing","Open-weight models","3. Pretraining","Medical Reasoning \u0026 Foundation Models","\u003cspan id=\"tool\"\u003eLLM (LLM \u0026 Tool)\u003c/span\u003e"],"readme":"\u003cimg alt=\"gpt-oss-120\" src=\"./docs/gpt-oss.svg\"\u003e\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://gpt-oss.com\"\u003e\u003cstrong\u003eTry gpt-oss\u003c/strong\u003e\u003c/a\u003e ·\n  \u003ca href=\"https://cookbook.openai.com/topic/gpt-oss\"\u003e\u003cstrong\u003eGuides\u003c/strong\u003e\u003c/a\u003e ·\n  \u003ca href=\"https://arxiv.org/abs/2508.10925\"\u003e\u003cstrong\u003eModel card\u003c/strong\u003e\u003c/a\u003e ·\n  \u003ca href=\"https://openai.com/index/introducing-gpt-oss/\"\u003e\u003cstrong\u003eOpenAI blog\u003c/strong\u003e\u003c/a\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eDownload \u003ca href=\"https://huggingface.co/openai/gpt-oss-120b\"\u003egpt-oss-120b\u003c/a\u003e and \u003ca href=\"https://huggingface.co/openai/gpt-oss-20b\"\u003egpt-oss-20b\u003c/a\u003e on Hugging Face\u003c/strong\u003e\n\u003c/p\u003e\n\n\u003cbr\u003e\n\nWelcome to the gpt-oss series, [OpenAI's open-weight models](https://openai.com/open-models/) designed for powerful reasoning, agentic tasks, and versatile developer use cases.\n\nWe're releasing two flavors of these open models:\n\n- `gpt-oss-120b` — for production, general purpose, high reasoning use cases that fit into a single 80GB GPU (like NVIDIA H100 or AMD MI300X) (117B parameters with 5.1B active parameters)\n- `gpt-oss-20b` — for lower latency, and local or specialized use cases (21B parameters with 3.6B active parameters)\n\nBoth models were trained using our [harmony response format][harmony] and should only be used with this format; otherwise, they will not work correctly.\n\n## Table of Contents\n- [Highlights](#highlights)\n- [Inference examples](#inference-examples)\n- [About this repository](#about-this-repository)\n- [Setup](#setup)\n- [Download the model](#download-the-model)\n- [Reference PyTorch implementation](#reference-pytorch-implementation)\n- [Reference Triton implementation (single GPU)](#reference-triton-implementation-single-gpu)\n- [Reference Metal implementation](#reference-metal-implementation)\n- [Harmony format \u0026 tools](#harmony-format--tools)\n- [Clients](#clients)\n- [Tools](#tools)\n- [Other details](#other-details)\n- [Contributing](#contributing)\n\n### Highlights\n\n- **Permissive Apache 2.0 license:** Build freely without copyleft restrictions or patent risk—ideal for experimentation, customization, and commercial deployment.\n- **Configurable reasoning effort:** Easily adjust the reasoning effort (low, medium, high) based on your specific use case and latency needs.\n- **Full chain-of-thought:** Provides complete access to the model's reasoning process, facilitating easier debugging and greater trust in outputs. This information is not intended to be shown to end users.\n- **Fine-tunable:** Fully customize models to your specific use case through parameter fine-tuning.\n- **Agentic capabilities:** Use the models' native capabilities for function calling, [web browsing](#browser), [Python code execution](#python), and Structured Outputs.\n- **MXFP4 quantization:** The models were post-trained with MXFP4 quantization of the MoE weights, making `gpt-oss-120b` run on a single 80GB GPU (like NVIDIA H100 or AMD MI300X) and the `gpt-oss-20b` model run within 16GB of memory. All evals were performed with the same MXFP4 quantization.\n\n### Inference examples\n\n#### Transformers\n\nYou can use `gpt-oss-120b` and `gpt-oss-20b` with the Transformers library. If you use Transformers' chat template, it will automatically apply the [harmony response format][harmony]. If you use `model.generate` directly, you need to apply the harmony format manually using the chat template or use our [`openai-harmony`][harmony] package.\n\n```python\nfrom transformers import pipeline\nimport torch\n\nmodel_id = \"openai/gpt-oss-120b\"\n\npipe = pipeline(\n    \"text-generation\",\n    model=model_id,\n    torch_dtype=\"auto\",\n    device_map=\"auto\",\n)\n\nmessages = [\n    {\"role\": \"user\", \"content\": \"Explain quantum mechanics clearly and concisely.\"},\n]\n\noutputs = pipe(\n    messages,\n    max_new_tokens=256,\n)\nprint(outputs[0][\"generated_text\"][-1])\n```\n\n[Learn more about how to use gpt-oss with Transformers.](https://cookbook.openai.com/articles/gpt-oss/run-transformers)\n\n#### vLLM\n\nvLLM recommends using [`uv`](https://docs.astral.sh/uv/) for Python dependency management. You can use vLLM to spin up an OpenAI-compatible web server. The following command will automatically download the model and start the server.\n\n```bash\nuv pip install --pre vllm==0.10.1+gptoss \\\n    --extra-index-url https://wheels.vllm.ai/gpt-oss/ \\\n    --extra-index-url https://download.pytorch.org/whl/nightly/cu128 \\\n    --index-strategy unsafe-best-match\n\nvllm serve openai/gpt-oss-20b\n```\n\n[Learn more about how to use gpt-oss with vLLM.](https://cookbook.openai.com/articles/gpt-oss/run-vllm)\n\nOffline Serve Code:\n- run this code after installing proper libraries as described, while additionally installing this:\n- `uv pip install openai-harmony`\n```python\n# source .oss/bin/activate\n\nimport os\nos.environ[\"VLLM_USE_FLASHINFER_SAMPLER\"] = \"0\"\n\nimport json\nfrom openai_harmony import (\n    HarmonyEncodingName,\n    load_harmony_encoding,\n    Conversation,\n    Message,\n    Role,\n    SystemContent,\n    DeveloperContent,\n)\n \nfrom vllm import LLM, SamplingParams\nimport os\n\n# --- 1) Render the prefill with Harmony ---\nencoding = load_harmony_encoding(HarmonyEncodingName.HARMONY_GPT_OSS)\n \nconvo = Conversation.from_messages(\n    [\n        Message.from_role_and_content(Role.SYSTEM, SystemContent.new()),\n        Message.from_role_and_content(\n            Role.DEVELOPER,\n            DeveloperContent.new().with_instructions(\"Always respond in riddles\"),\n        ),\n        Message.from_role_and_content(Role.USER, \"What is the weather like in SF?\"),\n    ]\n)\n \nprefill_ids = encoding.render_conversation_for_completion(convo, Role.ASSISTANT)\n \n# Harmony stop tokens (pass to sampler so they won't be included in output)\nstop_token_ids = encoding.stop_tokens_for_assistant_actions()\n \n# --- 2) Run vLLM with prefill ---\nllm = LLM(\n    model=\"openai/gpt-oss-20b\",\n    trust_remote_code=True,\n    gpu_memory_utilization = 0.95,\n    max_num_batched_tokens=4096,\n    max_model_len=5000,\n    tensor_parallel_size=1\n)\n \nsampling = SamplingParams(\n    max_tokens=128,\n    temperature=1,\n    stop_token_ids=stop_token_ids,\n)\n \noutputs = llm.generate(\n    prompt_token_ids=[prefill_ids],   # batch of size 1\n    sampling_params=sampling,\n)\n \n# vLLM gives you both text and token IDs\ngen = outputs[0].outputs[0]\ntext = gen.text\noutput_tokens = gen.token_ids  # \u003c-- these are the completion token IDs (no prefill)\n \n# --- 3) Parse the completion token IDs back into structured Harmony messages ---\nentries = encoding.parse_messages_from_completion_tokens(output_tokens, Role.ASSISTANT)\n \n# 'entries' is a sequence of structured conversation entries (assistant messages, tool calls, etc.).\nfor message in entries:\n    print(f\"{json.dumps(message.to_dict())}\")\n```\n\n#### PyTorch / Triton / Metal\n\nThese implementations are largely reference implementations for educational purposes and are not expected to be run in production.\n\n[Learn more below.](#reference-pytorch-implementation)\n\n#### Ollama\n\nIf you are trying to run `gpt-oss` on consumer hardware, you can use Ollama by running the following commands after [installing Ollama](https://ollama.com/download).\n\n```bash\n# gpt-oss-20b\nollama pull gpt-oss:20b\nollama run gpt-oss:20b\n\n# gpt-oss-120b\nollama pull gpt-oss:120b\nollama run gpt-oss:120b\n```\n\n[Learn more about how to use gpt-oss with Ollama.](https://cookbook.openai.com/articles/gpt-oss/run-locally-ollama)\n\n#### LM Studio\n\nIf you are using [LM Studio](https://lmstudio.ai/) you can use the following commands to download.\n\n```bash\n# gpt-oss-20b\nlms get openai/gpt-oss-20b\n# gpt-oss-120b\nlms get openai/gpt-oss-120b\n```\n\nCheck out our [awesome list](./awesome-gpt-oss.md) for a broader collection of gpt-oss resources and inference partners.\n\n## About this repository\n\nThis repository provides a collection of reference implementations:\n\n- **Inference:**\n  - [`torch`](#reference-pytorch-implementation) — a non-optimized [PyTorch](https://pytorch.org/) implementation for educational purposes only. Requires at least 4× H100 GPUs due to lack of optimization.\n  - [`triton`](#reference-triton-implementation-single-gpu) — a more optimized implementation using [PyTorch](https://pytorch.org/) \u0026 [Triton](https://github.com/triton-lang/triton) incl. using CUDA graphs and basic caching\n  - [`metal`](#reference-metal-implementation) — a Metal-specific implementation for running the models on Apple Silicon hardware\n- **Tools:**\n  - [`browser`](#browser) — a reference implementation of the browser tool the models got trained on\n  - [`python`](#python) — a stateless reference implementation of the python tool the model got trained on\n- **Client examples:**\n  - [`chat`](#terminal-chat) — a basic terminal chat application that uses the PyTorch or Triton implementations for inference along with the python and browser tools\n  - [`responses_api`](#responses-api) — an example Responses API compatible server that implements the browser tool along with other Responses-compatible functionality\n\n## Setup\n\n### Requirements\n\n- Python 3.12\n- On macOS: Install the Xcode CLI tools --\u003e `xcode-select --install`\n- On Linux: These reference implementations require CUDA\n- On Windows: These reference implementations have not been tested on Windows. Try using solutions like Ollama if you are trying to run the model locally.\n\n### Installation\n\nIf you want to try any of the code you can install it directly from [PyPI](https://pypi.org/project/gpt-oss/)\n\n```shell\n# if you just need the tools\npip install gpt-oss\n# if you want to try the torch implementation\npip install gpt-oss[torch]\n# if you want to try the triton implementation\npip install gpt-oss[triton]\n```\n\nIf you want to modify the code or try the metal implementation set the project up locally:\n\n```shell\ngit clone https://github.com/openai/gpt-oss.git\nGPTOSS_BUILD_METAL=1 pip install -e \".[metal]\"\n```\n\n## Download the model\n\nYou can download the model weights from the [Hugging Face Hub](https://huggingface.co/collections/openai/gpt-oss-68911959590a1634ba11c7a4) directly from Hugging Face CLI:\n\n```shell\n# gpt-oss-120b\nhf download openai/gpt-oss-120b --include \"original/*\" --local-dir gpt-oss-120b/\n\n# gpt-oss-20b\nhf download openai/gpt-oss-20b --include \"original/*\" --local-dir gpt-oss-20b/\n```\n\n## Reference PyTorch implementation\n\nWe include an inefficient reference PyTorch implementation in [gpt_oss/torch/model.py](gpt_oss/torch/model.py). This code uses basic PyTorch operators to show the exact model architecture, with a small addition of supporting tensor parallelism in MoE so that the larger model can run with this code (e.g., on 4xH100 or 2xH200). In this implementation, we upcast all weights to BF16 and run the model in BF16.\n\nTo run the reference implementation, install the dependencies:\n\n```shell\npip install -e \".[torch]\"\n```\n\nAnd then run:\n\n```shell\n# On 4xH100:\ntorchrun --nproc-per-node=4 -m gpt_oss.generate gpt-oss-120b/original/\n```\n\n## Reference Triton implementation (single GPU)\n\nWe also include an optimized reference implementation that uses [an optimized triton MoE kernel](https://github.com/triton-lang/triton/tree/main/python/triton_kernels/triton_kernels) that supports MXFP4. It also has some optimization on the attention code to reduce the memory cost. To run this implementation, the nightly version of triton and torch will be installed. This version can be run on a single 80GB GPU for `gpt-oss-120b`.\n\nTo install the reference Triton implementation run\n\n```shell\n# You need to install triton from source to use the triton implementation\ngit clone https://github.com/triton-lang/triton\ncd triton/\npip install -r python/requirements.txt\npip install -e . --verbose --no-build-isolation\npip install -e python/triton_kernels\n\n# Install the gpt-oss triton implementation\npip install -e \".[triton]\"\n```\n\nAnd then run:\n\n```shell\n# On 1xH100\nexport PYTORCH_CUDA_ALLOC_CONF=expandable_segments:True\npython -m gpt_oss.generate --backend triton gpt-oss-120b/original/\n```\n\nIf you encounter `torch.OutOfMemoryError`, make sure to turn on the expandable allocator to avoid crashes when loading weights from the checkpoint.\n\n## Reference Metal implementation\n\nAdditionally we are providing a reference implementation for Metal to run on Apple Silicon. This implementation is not production-ready but is accurate to the PyTorch implementation.\n\nThe implementation will get automatically compiled when running the `.[metal]` installation on an Apple Silicon device:\n\n```shell\nGPTOSS_BUILD_METAL=1 pip install -e \".[metal]\"\n```\n\nTo perform inference you'll need to first convert the SafeTensor weights from Hugging Face into the right format using:\n\n```shell\npython gpt_oss/metal/scripts/create-local-model.py -s \u003cmodel_dir\u003e -d \u003coutput_file\u003e\n```\n\nOr download the pre-converted weights:\n\n```shell\nhf download openai/gpt-oss-120b --include \"metal/*\" --local-dir gpt-oss-120b/metal/\nhf download openai/gpt-oss-20b --include \"metal/*\" --local-dir gpt-oss-20b/metal/\n```\n\nTo test it you can run:\n\n```shell\npython gpt_oss/metal/examples/generate.py gpt-oss-20b/metal/model.bin -p \"why did the chicken cross the road?\"\n```\n\n## Harmony format \u0026 tools\n\nAlong with the model, we are also releasing a new chat format library `harmony` to interact with the model. Check [this guide](https://cookbook.openai.com/articles/openai-harmony) for more info about harmony.\n\nWe also include two system tools for the model: browsing and python container. Check [gpt_oss/tools](gpt_oss/tools) for the tool implementation.\n\n## Clients\n\n### Terminal Chat\n\nThe terminal chat application is a basic example of how to use the harmony format together with the PyTorch, Triton, and vLLM implementations. It also exposes both the python and browser tool as optional tools that can be used.\n\n```bash\nusage: python -m gpt_oss.chat [-h] [-r REASONING_EFFORT] [-a] [-b] [--show-browser-results] [-p] [--developer-message DEVELOPER_MESSAGE] [-c CONTEXT] [--raw] [--backend {triton,torch,vllm}] FILE\n\nChat example\n\npositional arguments:\n  FILE                  Path to the SafeTensors checkpoint\n\noptions:\n  -h, --help            show this help message and exit\n  -r REASONING_EFFORT, --reasoning-effort REASONING_EFFORT\n                        Reasoning effort (default: low)\n  -a, --apply-patch     Make apply_patch tool available to the model (default: False)\n  -b, --browser         Use browser tool (default: False)\n  --show-browser-results\n                        Show browser results (default: False)\n  -p, --python          Use python tool (default: False)\n  --developer-message DEVELOPER_MESSAGE\n                        Developer message (default: )\n  -c CONTEXT, --context CONTEXT\n                        Max context length (default: 8192)\n  --raw                 Raw mode (does not render Harmony encoding) (default: False)\n  --backend {triton,torch,vllm}\n                        Inference backend (default: triton)\n```\n\n\u003e [!NOTE]\n\u003e The torch and triton implementations require original checkpoint under `gpt-oss-120b/original/` and `gpt-oss-20b/original/` respectively. While vLLM uses the Hugging Face converted checkpoint under `gpt-oss-120b/` and `gpt-oss-20b/` root directory respectively.\n\n### Responses API\n\nWe also include an example Responses API server. This server does not implement every feature and event of the Responses API but should be compatible with most of the basic use cases and serve as inspiration for anyone building their own server. Some of our inference partners are also offering their own Responses API.\n\nYou can start this server with the following inference backends:\n\n- `triton` — uses the triton implementation\n- `metal` — uses the metal implementation on Apple Silicon only\n- `ollama` — uses the Ollama /api/generate API as an inference solution\n- `vllm` — uses your installed vllm version to perform inference\n- `transformers` — uses your installed transformers version to perform local inference\n\n```bash\nusage: python -m gpt_oss.responses_api.serve [-h] [--checkpoint FILE] [--port PORT] [--inference-backend BACKEND]\n\nResponses API server\n\noptions:\n  -h, --help                    show this help message and exit\n  --checkpoint FILE             Path to the SafeTensors checkpoint\n  --port PORT                   Port to run the server on\n  --inference-backend BACKEND   Inference backend to use\n```\n\n### Codex\n\nWe support [codex](https://github.com/openai/codex) as a client for gpt-oss. To run the 20b version, set this to `~/.codex/config.toml`:\n\n```\ndisable_response_storage = true\nshow_reasoning_content = true\n\n[model_providers.local]\nname = \"local\"\nbase_url = \"http://localhost:11434/v1\"\n\n[profiles.oss]\nmodel = \"gpt-oss:20b\"\nmodel_provider = \"local\"\n```\n\nThis will work with any chat completions-API compatible server listening on port 11434, like ollama. Start the server and point codex to the oss model:\n\n```\nollama run gpt-oss:20b\ncodex -p oss\n```\n\n## Tools\n\n### Browser\n\n\u003e [!WARNING]\n\u003e This implementation is purely for educational purposes and should not be used in production. You should implement your own equivalent of the [`YouComBackend`](gpt_oss/tools/simple_browser/backend.py) or [`ExaBackend`](gpt_oss/tools/simple_browser/backend.py) class with your own browsing environment. Currently we have available `YouComBackend` and `ExaBackend`.\n\nBoth gpt-oss models were trained with the capability to browse using the `browser` tool that exposes the following three methods:\n\n- `search` to search for key phrases\n- `open` to open a particular page\n- `find` to look for contents on a page\n\n#### Usage\n\nTo enable the browser tool, you'll have to place the definition into the `system` message of your harmony formatted prompt. You can either use the `with_browser_tool()` method if your tool implements the full interface or modify the definition using `with_tools()`. For example:\n\n```python\nimport datetime\nimport os\nfrom gpt_oss.tools.simple_browser import SimpleBrowserTool\nfrom gpt_oss.tools.simple_browser.backend import ExaBackend, YouComBackend\nfrom openai_harmony import SystemContent, Message, Conversation, Role, load_harmony_encoding, HarmonyEncodingName\n\nencoding = load_harmony_encoding(HarmonyEncodingName.HARMONY_GPT_OSS)\n\n# You.com is the default browser backend and requires YDC_API_KEY.\n# To use Exa instead, set BROWSER_BACKEND=exa and EXA_API_KEY.\ntool_backend = os.getenv(\"BROWSER_BACKEND\", \"youcom\")\nif tool_backend == \"youcom\":\n    backend = YouComBackend(source=\"web\")\nelif tool_backend == \"exa\":\n    backend = ExaBackend(source=\"web\")\nelse:\n    raise ValueError(f\"Invalid tool backend: {tool_backend}\")\nbrowser_tool = SimpleBrowserTool(backend=backend)\n\n# create a basic system prompt\nsystem_message_content = SystemContent.new().with_conversation_start_date(\n    datetime.datetime.now().strftime(\"%Y-%m-%d\")\n)\n\n# if you want to use the browser tool\nif use_browser_tool:\n    # enables the tool\n    system_message_content = system_message_content.with_tools(browser_tool.tool_config)\n    # alternatively you could use the following if your tool is not stateless\n    system_message_content = system_message_content.with_browser_tool()\n\n# construct the system message\nsystem_message = Message.from_role_and_content(Role.SYSTEM, system_message_content)\n\n# create the overall prompt\nmessages = [system_message, Message.from_role_and_content(Role.USER, \"What's the weather in SF?\")]\nconversation = Conversation.from_messages(messages)\n\n# convert to tokens\ntoken_ids = encoding.render_conversation_for_completion(conversation, Role.ASSISTANT)\n\n# perform inference\n# ...\n\n# parse the output\nmessages = encoding.parse_messages_from_completion_tokens(output_tokens, Role.ASSISTANT)\nlast_message = messages[-1]\nif last_message.recipient.startswith(\"browser\"):\n  # perform browser call\n  response_messages = await browser_tool.process(last_message)\n\n  # extend the current messages and run inference again\n  messages.extend(response_messages)\n```\n\n#### Details\n\nTo control the context window size this tool uses a scrollable window of text that the model can interact with. So it might fetch the first 50 lines of a page and then scroll to the next 20 lines after that. The model has also been trained to then use citations from this tool in its answers.\n\nTo improve performance the tool caches requests so that the model can revisit a different part of a page without having to reload the page. For that reason you should create a new browser instance for every request.\n\n### Python\n\nThe model was trained to use a python tool to perform calculations and other actions as part of its chain-of-thought. During the training the model used a stateful tool which makes running tools between CoT loops easier. This reference implementation, however, uses a stateless mode. As a result the PythonTool defines its own tool description to override the definition in [`openai-harmony`][harmony].\n\n\u003e [!WARNING]\n\u003e This implementation runs in a permissive Docker container which could be problematic in cases like prompt injections. It's serving as an example and you should consider implementing your own container restrictions in production.\n\n#### Usage\n\nTo enable the python tool, you'll have to place the definition into the `system` message of your harmony formatted prompt. You can either use the `with_python()` method if your tool implements the full interface or modify the definition using `with_tools()`. For example:\n\n```python\nimport datetime\nfrom gpt_oss.tools.python_docker.docker_tool import PythonTool\nfrom openai_harmony import SystemContent, Message, Conversation, Role, load_harmony_encoding, HarmonyEncodingName\n\nencoding = load_harmony_encoding(HarmonyEncodingName.HARMONY_GPT_OSS)\n\npython_tool = PythonTool()\n\n# create a basic system prompt\nsystem_message_content = SystemContent.new().with_conversation_start_date(\n    datetime.datetime.now().strftime(\"%Y-%m-%d\")\n)\n\n# if you want to use the python tool\nif use_python_tool:\n    # enables the tool making sure that the prompt gets set with the stateless tool description\n    system_message_content = system_message_content.with_tools(python_tool.tool_config)\n    # alternatively you could use the following if your tool is not stateless\n    system_message_content = system_message_content.with_python()\n\n# construct the system message\nsystem_message = Message.from_role_and_content(Role.SYSTEM, system_message_content)\n\n# create the overall prompt\nmessages = [system_message, Message.from_role_and_content(Role.USER, \"What's the square root of 9001?\")]\nconversation = Conversation.from_messages(messages)\n\n# convert to tokens\ntoken_ids = encoding.render_conversation_for_completion(conversation, Role.ASSISTANT)\n\n# perform inference\n# ...\n\n# parse the output\nmessages = encoding.parse_messages_from_completion_tokens(output_tokens, Role.ASSISTANT)\nlast_message = messages[-1]\nif last_message.recipient == \"python\":\n  # perform python call\n  response_messages = await python_tool.process(last_message)\n\n  # extend the current messages and run inference again\n  messages.extend(response_messages)\n```\n\n### Apply Patch\n\n`apply_patch` can be used to create, update or delete files locally.\n\n## Other details\n\n### Precision format\n\nWe released the models with native quantization support. Specifically, we use [MXFP4](https://www.opencompute.org/documents/ocp-microscaling-formats-mx-v1-0-spec-final-pdf) for the linear projection weights in the MoE layer. We store the MoE tensor in two parts:\n\n- `tensor.blocks` stores the actual fp4 values. We pack every two values in one `uint8` value.\n- `tensor.scales` stores the block scale. The block scaling is done among the last dimension for all MXFP4 tensors.\n\nAll other tensors will be in BF16. We also recommend using BF16 as the activation precision for the model.\n\n### Recommended Sampling Parameters\n\nWe recommend sampling with `temperature=1.0` and `top_p=1.0`.\n\n## Contributing\n\nThe reference implementations in this repository are meant as a starting point and inspiration. Outside of bug fixes we do not intend to accept new feature contributions. If you build implementations based on this code such as new tool implementations you are welcome to contribute them to the [`awesome-gpt-oss.md`](./awesome-gpt-oss.md) file.\n\n[harmony]: https://github.com/openai/harmony\n\n## Citation\n\n```bibtex\n@misc{openai2025gptoss120bgptoss20bmodel,\n      title={gpt-oss-120b \u0026 gpt-oss-20b Model Card}, \n      author={OpenAI},\n      year={2025},\n      eprint={2508.10925},\n      archivePrefix={arXiv},\n      primaryClass={cs.CL},\n      url={https://arxiv.org/abs/2508.10925}, \n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenai%2Fgpt-oss","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopenai%2Fgpt-oss","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenai%2Fgpt-oss/lists"}