ollama-python Documentation

File: README.md Copy Chapter

Ollama Python Library

The Ollama Python library provides the easiest way to integrate Python 3.8+ projects with Ollama.

Prerequisites Copy Chapter

• Ollama should be installed and running
• Pull a model to use with the library: ollama pull <model> e.g. ollama pull gemma3
  • See Ollama.com for more information on the models available.

Install Copy Chapter

pip install ollama

Usage Copy Chapter

from ollama import chat
from ollama import ChatResponse

response: ChatResponse = chat(model='gemma3', messages=[
  {
    'role': 'user',
    'content': 'Why is the sky blue?',
  },
])
print(response['message']['content'])
# or access fields directly from the response object
print(response.message.content)

See _types.py for more information on the response types.

Streaming responses Copy Chapter

Response streaming can be enabled by setting stream=True.

from ollama import chat

stream = chat(
    model='gemma3',
    messages=[{'role': 'user', 'content': 'Why is the sky blue?'}],
    stream=True,
)

for chunk in stream:
  print(chunk['message']['content'], end='', flush=True)

Cloud Models Copy Chapter

Run larger models by offloading to Ollama’s cloud while keeping your local workflow.

• Supported models: deepseek-v3.1:671b-cloud, gpt-oss:20b-cloud, gpt-oss:120b-cloud, kimi-k2:1t-cloud, qwen3-coder:480b-cloud, kimi-k2-thinking See Ollama Models - Cloud for more information

Run via local Ollama Copy Section

1. Sign in (one-time):

ollama signin

2. Pull a cloud model:

ollama pull gpt-oss:120b-cloud

3. Make a request:

from ollama import Client

client = Client()

messages = [
  {
    'role': 'user',
    'content': 'Why is the sky blue?',
  },
]

for part in client.chat('gpt-oss:120b-cloud', messages=messages, stream=True):
  print(part.message.content, end='', flush=True)

Cloud API (ollama.com) Copy Section

Access cloud models directly by pointing the client at https://ollama.com.

1. Create an API key from ollama.com , then set:

export OLLAMA_API_KEY=your_api_key

2. (Optional) List models available via the API:

curl https://ollama.com/api/tags

3. Generate a response via the cloud API:

import os
from ollama import Client

client = Client(
    host='https://ollama.com',
    headers={'Authorization': 'Bearer ' + os.environ.get('OLLAMA_API_KEY')}
)

messages = [
  {
    'role': 'user',
    'content': 'Why is the sky blue?',
  },
]

for part in client.chat('gpt-oss:120b', messages=messages, stream=True):
  print(part.message.content, end='', flush=True)

Custom client Copy Chapter

A custom client can be created by instantiating Client or AsyncClient from ollama.

All extra keyword arguments are passed into the httpx.Client.

from ollama import Client
client = Client(
  host='http://localhost:11434',
  headers={'x-some-header': 'some-value'}
)
response = client.chat(model='gemma3', messages=[
  {
    'role': 'user',
    'content': 'Why is the sky blue?',
  },
])

Async client Copy Chapter

The AsyncClient class is used to make asynchronous requests. It can be configured with the same fields as the Client class.

import asyncio
from ollama import AsyncClient

async def chat():
  message = {'role': 'user', 'content': 'Why is the sky blue?'}
  response = await AsyncClient().chat(model='gemma3', messages=[message])

asyncio.run(chat())

Setting stream=True modifies functions to return a Python asynchronous generator:

import asyncio
from ollama import AsyncClient

async def chat():
  message = {'role': 'user', 'content': 'Why is the sky blue?'}
  async for part in await AsyncClient().chat(model='gemma3', messages=[message], stream=True):
    print(part['message']['content'], end='', flush=True)

asyncio.run(chat())

API Copy Chapter

The Ollama Python library's API is designed around the Ollama REST API

Chat Copy Section

ollama.chat(model='gemma3', messages=[{'role': 'user', 'content': 'Why is the sky blue?'}])

Generate Copy Section

ollama.generate(model='gemma3', prompt='Why is the sky blue?')

List Copy Section

ollama.list()

Show Copy Section

ollama.show('gemma3')

Create Copy Section

ollama.create(model='example', from_='gemma3', system="You are Mario from Super Mario Bros.")

Copy Copy Section

ollama.copy('gemma3', 'user/gemma3')

Delete Copy Section

ollama.delete('gemma3')

Pull Copy Section

ollama.pull('gemma3')

Push Copy Section

ollama.push('user/gemma3')

Embed Copy Section

ollama.embed(model='gemma3', input='The sky is blue because of rayleigh scattering')

Embed (batch) Copy Section

ollama.embed(model='gemma3', input=['The sky is blue because of rayleigh scattering', 'Grass is green because of chlorophyll'])

Ps Copy Section

ollama.ps()

Errors Copy Chapter

Errors are raised if requests return an error status or if an error is detected while streaming.

model = 'does-not-yet-exist'

try:
  ollama.chat(model)
except ollama.ResponseError as e:
  print('Error:', e.error)
  if e.status_code == 404:
    ollama.pull(model)

File: examples/README.md Copy Chapter

Running Examples

Run the examples in this directory with:

# Run example
python3 examples/<example>.py

# or with uv
uv run examples/<example>.py

See ollama/docs/api.md for full API documentation

Chat - Chat with a model Copy Section

• chat.py
• async-chat.py
• chat-stream.py - Streamed outputs
• chat-with-history.py - Chat with model and maintain history of the conversation

Generate - Generate text with a model Copy Section

• generate.py
• async-generate.py
• generate-stream.py - Streamed outputs
• fill-in-middle.py - Given a prefix and suffix, fill in the middle

Tools/Function Calling - Call a function with a model Copy Section

• tools.py - Simple example of Tools/Function Calling
• async-tools.py
• multi-tool.py - Using multiple tools, with thinking enabled

gpt-oss

• gpt-oss-tools.py
• gpt-oss-tools-stream.py

Web search Copy Section

An API key from Ollama's cloud service is required. You can create one here.

export OLLAMA_API_KEY="your_api_key_here"

• web-search.py
• web-search-gpt-oss.py - Using browser research tools with gpt-oss

MCP server

The MCP server can be used with an MCP client like Cursor, Cline, Codex, Open WebUI, Goose, and more.

uv run examples/web-search-mcp.py

Configuration to use with an MCP client:

{
  "mcpServers": {
    "web_search": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "path/to/ollama-python/examples/web-search-mcp.py"],
      "env": { "OLLAMA_API_KEY": "your_api_key_here" }
    }
  }
}

• web-search-mcp.py

Multimodal with Images - Chat with a multimodal (image chat) model Copy Section

• multimodal-chat.py
• multimodal-generate.py

Image Generation (Experimental) - Generate images with a model Copy Section

Note: Image generation is experimental and currently only available on macOS.

• generate-image.py

Structured Outputs - Generate structured outputs with a model Copy Section

• structured-outputs.py
• async-structured-outputs.py
• structured-outputs-image.py

Ollama List - List all downloaded models and their properties Copy Section

• list.py

Ollama Show - Display model properties and capabilities Copy Section

• show.py

Ollama ps - Show model status with CPU/GPU usage Copy Section

• ps.py

Ollama Pull - Pull a model from Ollama Copy Section

Requirement: pip install tqdm

• pull.py

Ollama Create - Create a model from a Modelfile Copy Section

• create.py

Ollama Embed - Generate embeddings with a model Copy Section

• embed.py

Thinking - Enable thinking mode for a model Copy Section

• thinking.py

Thinking (generate) - Enable thinking mode for a model Copy Section

• thinking-generate.py

Thinking (levels) - Choose the thinking level Copy Section

• thinking-levels.py