Skip to content

Installation

This guide will help you install zk-chat on your system.

System Requirements

  • Python: 3.11 or higher
  • Operating System: macOS, Linux (Windows support is experimental)
  • LLM Backend: Either Ollama (local) or OpenAI API access

Prerequisites

If you want to use local AI models, you'll need to install Ollama:

brew install ollama

curl -fsSL https://ollama.com/install.sh | sh

After installing Ollama, pull a model:

ollama pull qwen3:8b

Model Recommendations (2025)

Choose based on your available RAM:

64GB+ RAM (High-End): - gpt-oss:120b - Most capable for RAG and reasoning - qwen3:32b - Latest generation, very versatile

36-48GB RAM (Mid-Range): - gpt-oss:20b - Excellent balance, best for RAG tasks - gemma3:27b - Most capable single-GPU model with vision - qwen3:14b - Fast and capable

16-32GB RAM (Standard): - qwen3:8b - Recommended - Fast, versatile, excellent for RAG - qwen2.5:7b - Proven alternative, very reliable - mistral:7b - Proven reliable performer

For visual analysis: - gemma3:27b - Recommended - Best vision capabilities - qwen3-vl:8b - Fast and capable for images

For OpenAI API

If you prefer to use OpenAI's API instead of local models:

  1. Get an API key from OpenAI
  2. Set the environment variable:
export OPENAI_API_KEY=your_api_key_here

Installation Methods

pipx installs Python applications in isolated environments, preventing dependency conflicts.

Install pipx:

brew install pipx
pipx ensurepath

python3 -m pip install --user pipx
python3 -m pipx ensurepath

Install zk-chat:

pipx install zk-chat

Upgrade zk-chat:

pipx upgrade zk-chat

Install plugins:

# Example: Wikipedia plugin
pipx inject zk-chat zk-rag-wikipedia

# Example: Image generator plugin
pipx inject zk-chat zk-rag-image-generator

Method 2: Using pip in a Virtual Environment

If you prefer managing your own virtual environment:

Create and activate a virtual environment:

cd $HOME
python3 -m venv .venv
source .venv/bin/activate

Install zk-chat:

pip install zk-chat

Install plugins (optional):

pip install zk-rag-wikipedia
pip install zk-rag-image-generator

Verify Installation

Verify that zk-chat is installed correctly:

zk-chat --help

You should see the command-line help output with available commands.

First-Time Setup

When you first run zk-chat, you'll need to provide:

  1. Vault Path: The location of your Zettelkasten folder
  2. Model Selection: Choose an LLM model for chat
  3. Visual Model (optional): Choose a model for image analysis

Example first run:

zk-chat interactive --vault /path/to/your/vault

The tool will:

  1. Prompt you to select a chat model
  2. Ask if you want visual analysis capabilities
  3. Build an initial index of your documents

Index Building

The first index build may take a few minutes depending on the size of your Zettelkasten.

Next Steps

Troubleshooting

Ollama Connection Issues

If zk-chat can't connect to Ollama:

  1. Ensure Ollama is running: 

    ollama serve

  2. Check that the model is available: 

    ollama list

Import Errors

If you encounter import errors, ensure you have the correct Python version:

python --version  # Should be 3.11 or higher

Permission Issues

If you get permission errors during installation:

  • Use pipx instead of system-wide pip installation
  • Or create a virtual environment as shown in Method 2