Guide · Open source

How to use ollama-python: install, chat, stream and embed

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

ollama-python is the official Python library for sending requests to a model running through Ollama. It wraps Ollama's REST API so that chat, generation and embedding calls look like ordinary Python functions. This guide shows you how to install it, make your first request, stream output, use the async client and handle errors.

Ollamaollama/ollama-python · ★ 10.7k · MIT Install options & downloads

Quick start

1Install Ollama and start it. Download Ollama from ollama.com/download and make sure it is installed and running.
2Pull a model. Run ollama pull gemma4 or another model from ollama.com/search.
3Install the library. Run pip install ollama in your Python environment using Python 3.8 or newer.
4Send a chat request. Call chat with a model name and a messages list, then print response.message.content.
5Enable streaming. Pass stream=True and loop over the chunks to print text as it arrives.
6Handle errors. Wrap calls in try and catch ollama.ResponseError to read the error and status code.

What you need before you install ollama-python

You need Python 3.8 or newer and Ollama installed and running. The library cannot do anything until Ollama is running and at least one model has been pulled.

Install Ollama from the download page at ollama.com/download.
Pull a model with ollama pull <model>, for example ollama pull gemma4.
Find other available models at ollama.com/search.

ollama pull gemma4

Install the ollama Python package with pip

The library is installed with pip. The package name is ollama, and you import it as ollama in your code.

pip install ollama

Send your first chat request

Import chat, pass a model name and a list of messages, then print the reply. The response can be read like a dictionary or through its attributes.

Use 'role': 'user' for your prompt and 'content' for the text.
response['message']['content'] and response.message.content return the same text.

from ollama import chat
from ollama import ChatResponse

response: ChatResponse = chat(
  model='gemma4',
  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)

Stream responses as they are generated

Set stream=True to receive the reply in chunks instead of waiting for the full answer. Each chunk is printed as it arrives.

from ollama import chat

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

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

Use the async client and other API calls

AsyncClient makes asynchronous requests. With stream=True, the async version returns an asynchronous generator you read with async for.

The library also exposes generate, list, show, create, copy, delete, pull, push, embed, and ps. Embed accepts a single string or a list of strings for batch processing.

Use Client or AsyncClient to set a custom host or headers; extra keyword arguments are passed to httpx.Client.
Use ollama.embed with a list of inputs for batch text processing.

import asyncio
from ollama import AsyncClient


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


asyncio.run(chat())

Handle errors

Errors are raised when a request returns an error status or when an error appears during streaming. Catch ollama.ResponseError to read the message and status code. The README example pulls the model when it gets a 404.

e.error holds the error message.
e.status_code holds the HTTP status code.

import ollama

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)

What people use it for

Adding a local model to a Python script that answers questions about text files.
Building an app backend that streams responses to users with stream=True.
Running async requests inside an asyncio program with AsyncClient.
Generating embeddings for a batch of sentences in a text-processing pipeline.
Calling larger cloud models from Python through Ollama's cloud features, as described in the README.

Frequently asked questions

Is ollama-python free to use?

ollama-python is released under the MIT licence, according to its project information. Ollama itself must also be installed and running for the library to work.

What do I need before I can use ollama-python?

You need Python 3.8 or newer, and Ollama installed and running. You also need to pull at least one model, such as with ollama pull gemma4, before making requests.

How do I install ollama-python?

Run pip install ollama. The package is named ollama and is imported as ollama in Python code.

Does ollama-python support streaming and async?

Yes. Set stream=True to receive responses in chunks, and use AsyncClient with await for asynchronous requests. Streaming with the async client returns an asynchronous generator.

Why does my ollama-python call fail with a 404 error?

A 404 usually means the model you named is not available. The README shows catching ollama.ResponseError and calling ollama.pull(model) when the status code is 404. Check the model name and that it has been pulled.

What are the alternatives to ollama-python?

Comparable projects listed for this item are openai-python, litellm and langchain-ollama. ollama-python is the one that talks directly to Ollama's REST API, so it fits best when you only need Ollama.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Use ollama-python if you write Python and want to call Ollama models from a script or app without raw HTTP requests. It is a library, not a chat app, and the README only covers Python usage, so skip it if you want a ready-made interface or do not code.

Install options & downloads