Ollama Doctor

A lightweight command-line utility for checking local Ollama models — RAM fit, side-by-side comparisons, and real response-time benchmarks — before you build anything around them.

Overview

Ollama Doctor helps you understand your local Ollama environment by:

• Listing installed Ollama models with estimated RAM needs and download size
• Comparing multiple models' RAM requirements side by side
• Checking whether a specific model fits your available system memory
• Benchmarking a model's real response time and suggesting a timeout value
• Showing what's currently loaded in memory right now

The goal is to catch problems — like a model needing more RAM than you have — in seconds, instead of discovering it partway through building something around it.

Features

list — installed models

MODEL                      EST. RAM   DOWNLOAD    STATUS
--------------------------------------------------------
llama3.1:8b                  6.0 GB     4.6 GB    Fits
deepseek-r1:14b              10.5 GB    9.0 GB    Fits

check — does one model fit?

$ ollama-doctor check llama3.1:8b
PASS - llama3.1:8b (4.6GB) fits in available RAM (23.4GB)

compare — multiple models side by side

$ ollama-doctor compare llama3.1:8b deepseek-r1:14b llama3.1:70b
PASS - llama3.1:8b (4.6GB) fits in available RAM (23.4GB)
PASS - deepseek-r1:14b (9.0GB) fits in available RAM (23.4GB)
FAIL - llama3.1:70b (42.0GB) needs 18.6GB more RAM than available (23.4GB)

bench — real response time

$ ollama-doctor bench llama3.1:8b
llama3.1:8b: 0.19s response time — suggested timeout: 0.57s

status — what's loaded right now

Shows currently loaded models (from Ollama's /api/ps) plus current available RAM.

RAM Estimation

For models without a known downloaded size (or for quick comparison), estimation uses a simple heuristic based on parameter count:

Estimated RAM = Model Parameters (B) × 0.75 GB

Examples:

8B model  → ~6 GB RAM
14B model → ~10.5 GB RAM
70B model → ~52.5 GB RAM

This is a rough estimate tuned for typical 4-bit quantized Ollama models — actual usage varies by quantization level. For installed models, list also shows real download size, which is a more accurate fit signal than the estimate alone.

Project Structure

ollama-doctor/
│
├── ollama_doctor/
│   ├── cli.py              # argparse entrypoint, wires up all subcommands
│   ├── ollama_api.py       # local Ollama client — /api/tags, /api/ps, /api/generate
│   ├── system.py           # available RAM check (psutil)
│   ├── catalog.py          # ollamadb.dev client (planned — not yet wired in)
│   ├── estimate.py         # parameter-size → RAM estimate heuristic
│   │
│   └── commands/
│       ├── check.py        # ollama-doctor check <model>
│       ├── compare.py      # ollama-doctor compare <model1> <model2> ...
│       ├── list.py         # ollama-doctor list
│       ├── bench.py        # ollama-doctor bench <model>
│       └── status.py       # ollama-doctor status
│
├── README.md
└── pyproject.toml

Installation

git clone <repository-url>
cd ollama-doctor
pip install -e .

This registers the ollama-doctor command via the project's entry point — no need to invoke modules directly.

Usage

ollama-doctor list
ollama-doctor check llama3.1:8b
ollama-doctor compare llama3.1:8b deepseek-r1:14b llama3.1:70b
ollama-doctor bench llama3.1:8b
ollama-doctor status

Requirements

• Python 3.9+
• Ollama installed and running locally
• requests, psutil

Current Limitations

Model name parsing (estimate.py) is currently optimized for simple parameter_size labels as returned by Ollama's API (e.g. "8.0B").

Not yet handling variation in quantization suffixes within model tags themselves, e.g.:

deepseek-r1:70b-q4_K_M
gemma3:27b-it

Future Improvements

Planned features:

• list --fits / --role draft|review / --search filters
• Colored terminal output
• More accurate RAM estimates based on quantization level
• GPU/VRAM detection
• Automatic Ollama health diagnostics
• Support for more complex model tag formats

License

MIT License