Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/openai/openai-cookbook/llms.txt

Use this file to discover all available pages before exploring further.

Running gpt-oss locally means your prompts, completions, and reasoning traces stay entirely on your own hardware — no API keys, no data leaving your machine, and no per-token costs after setup. Both Ollama and LM Studio handle the OpenAI Harmony chat template automatically, so you can point the standard OpenAI Python client at your local server without changing your application code. This guide covers both tools and helps you pick the right one for your setup.

Hardware requirements

Both model sizes ship in MXFP4 quantized format. This sets the minimum VRAM (or unified memory on Apple Silicon) you need:
ModelMinimum VRAMRecommended hardware
gpt-oss-20b16 GBHigh-end consumer GPU (RTX 4090), Apple Silicon Mac (M2 Pro or later)
gpt-oss-120b60 GBMulti-GPU workstation, Mac Pro with M2 Ultra, or H100-class server
You can offload layers to CPU RAM if you are short on VRAM, but expect significantly slower generation speeds. For server deployments with dedicated GPU hardware, see the vLLM guide.

Ollama

Ollama is the fastest way to get gpt-oss running. It installs as a single binary, manages model downloads, applies the Harmony chat template automatically, and exposes an OpenAI-compatible HTTP API at localhost:11434.

Install and pull the model

1

Install Ollama

Download and install Ollama for your operating system from ollama.com/download, or use the install script on Mac and Linux:
# Install Ollama (mac/linux)
curl -fsSL https://ollama.com/install.sh | sh
On Windows, download and run the .exe installer from the Ollama website.
2

Pull the model

Download the model weights. This will take a few minutes depending on your connection:
# Pull the model
ollama pull gpt-oss-20b
To use the full 120B model instead:
ollama pull gpt-oss-120b
3

Run the model

Start an interactive chat session directly in your terminal:
# Run the model
ollama run gpt-oss-20b
Ollama applies the Harmony chat template and handles chain-of-thought routing automatically. Type your message and press Enter to start the conversation.

Connect with the OpenAI Python client

Ollama exposes a Chat Completions-compatible API at http://localhost:11434/v1. Point the OpenAI Python client at this URL to use it as a drop-in replacement:
from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:11434/v1",
    api_key="ollama"  # required but unused
)

response = client.chat.completions.create(
    model="gpt-oss-20b",
    messages=[{"role": "user", "content": "Explain quantum entanglement simply."}]
)
print(response.choices[0].message.content)
If you’ve used the OpenAI Python client before, this is the only change needed — the rest of your code stays the same.

Function calling with Ollama

Ollama supports function calling through the standard tools parameter:
tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Get current weather in a given city",
            "parameters": {
                "type": "object",
                "properties": {"city": {"type": "string"}},
                "required": ["city"]
            },
        },
    }
]

response = client.chat.completions.create(
    model="gpt-oss-20b",
    messages=[{"role": "user", "content": "What's the weather in Berlin right now?"}],
    tools=tools
)

print(response.choices[0].message)
The gpt-oss models perform tool calls as part of their chain-of-thought. When handling a tool call response, pass the returned reasoning back into the next request alongside the tool output so the model can continue its reasoning correctly.

Agents SDK integration

To use gpt-oss via Ollama with the OpenAI Agents SDK, route requests through LiteLLM:
import asyncio
from agents import Agent, Runner, function_tool, set_tracing_disabled
from agents.extensions.models.litellm_model import LitellmModel

set_tracing_disabled(True)

@function_tool
def get_weather(city: str):
    return f"The weather in {city} is sunny."

async def main():
    agent = Agent(
        name="Assistant",
        instructions="You are a helpful assistant.",
        model=LitellmModel(model="ollama/gpt-oss-20b", api_key="ollama"),
        tools=[get_weather],
    )
    result = await Runner.run(agent, "What's the weather in Tokyo?")
    print(result.final_output)

if __name__ == "__main__":
    asyncio.run(main())

Performance tips

  • Apple Silicon: Both Ollama and LM Studio use Metal GPU acceleration on Apple Silicon Macs automatically. The gpt-oss-20b model fits comfortably in the unified memory of M2 Pro (16 GB) or better.
  • Quantization: Both tools use MXFP4 quantization by default, which provides good performance while keeping memory usage low. There is currently no alternative quantization available for gpt-oss models.
  • CPU offloading: If you have less VRAM than the model requires, layers can spill to CPU RAM, but generation will be noticeably slower. Consider using the 20b model if the 120b does not fit in your VRAM.
  • Context length: Longer contexts require more memory and slow down generation. Start with shorter prompts when testing on hardware near the minimum spec.
  • Background applications: Close other GPU-intensive applications before loading the model to maximize available VRAM.

Next steps

gpt-oss overview

Learn about the Harmony response format, model variants, and when to choose self-hosting over the API.

Fine-tune with Hugging Face

Fine-tune gpt-oss on your own dataset using Hugging Face Transformers and TRL.

Build docs developers (and LLMs) love