A complete, beginner-safe guide to installing Odysseus AI on Windows 10 or Windows 11. PowerShell commands, Python and Git prerequisites, Ollama connection, and fixes for every common Windows error — including the script execution policy, port 7000 conflicts and missing C++ build tools.
A clean Windows install with these four prerequisites in place takes the Odysseus AI install from 15 minutes down to 8 minutes. Skip a step and you'll likely hit one of the errors covered later on this page.
Odysseus AI runs on both Windows 10 and Windows 11 with no functional differences. Older Windows 10 builds before 19044 (the 21H2 update) lack the modern PowerShell features used by the launcher script. Press Win + R, type winver, hit Enter, and confirm your build number before proceeding.
Download the latest Python 3.11+ installer from python.org/downloads. Critically: tick the "Add Python to PATH" checkbox on the very first screen of the installer. If you miss it, every PowerShell command that calls python will silently fall back to the Microsoft Store stub and break the Odysseus AI install.
Verify after install:
Download from git-scm.com/download/win. Accept all defaults during install — the default editor and PATH options are fine. Git for Windows ships with Git Bash, which can substitute for PowerShell if you prefer Unix-style commands.
Odysseus AI itself is small (~200 MB), but the Python virtual environment, dependencies, and your first downloaded model can easily push past 5 GB. If you plan to run multiple models, budget 20 GB. Keep the install on a fast SSD if you have one — model load times scale directly with disk speed.
Open PowerShell — not Command Prompt — in a folder where you want the project to live. Right-click the folder in Explorer and pick "Open in Terminal" (Windows 11) or "Open PowerShell window here" (Windows 10 with Shift+Right-click).
The official Odysseus AI repo is hosted on GitHub under pewdiepie-archdaemon/odysseus. Always clone from this exact path — there are mirror and impostor repositories that look identical at a glance.
If you see git: The term 'git' is not recognized, Git for Windows isn't installed or isn't on your PATH — close PowerShell, reinstall Git, and reopen.
A virtual environment isolates Odysseus AI's Python dependencies from anything else on your system. The launcher script will create one automatically — but if you want to do it manually for control:
Your PowerShell prompt should now show (venv) at the start of the line. If activation fails with a script-execution error, jump to Common Windows errors below.
The included PowerShell script handles dependency install, database setup, and starting the server. It's safe to re-run later if anything goes wrong.
First run takes 3–8 minutes while pip downloads dependencies. Watch the terminal output for the admin password — it's printed exactly once, in plain text, around the time you see "Starting Odysseus AI on port 7000". Copy it before scrolling away.
Once the launcher prints Uvicorn running on http://127.0.0.1:7000, switch to your browser:
Log in with username admin and the password from the terminal. You're inside the Odysseus AI workspace. The model dropdown will be empty — that's expected. The next section connects it to Ollama.
Odysseus AI is a workspace, not a model — it needs a backend to do anything useful. Ollama is the simplest backend for Windows: a free, native installer that runs in your system tray and serves models on localhost:11434.
Download from ollama.com/download/windows and run the installer. After install, Ollama runs as a background service — you'll see its icon in the system tray. No additional configuration is needed on Windows.
Open a fresh PowerShell window (Ollama needs to be running in the background). Pull a small model that fits 8–16 GB of RAM:
Inside the Odysseus AI workspace, click the settings gear → Providers → Add Provider. Pick "OpenAI-compatible" and use these values:
Save, refresh the page, and your pulled model should appear in the model dropdown at the top of the chat panel. Send a message to confirm Odysseus AI is talking to Ollama.
Answer four questions about your Windows setup. The generator outputs a clean, copy-ready command block tailored to your situation — Windows version, Python state, GPU plan, and whether you'd rather run native or in WSL2.
Builds the right command sequence for your machine so you skip the guesswork.
These six cover roughly 90% of failed Odysseus AI installs on Windows. Match your terminal output against the error text in each card and apply the fix below.
By default, Windows blocks PowerShell scripts for security. Bypass it for the current PowerShell session only — this is the safe scope and reverts when you close the window.
Python isn't on your PATH. Either reinstall Python with the "Add to PATH" checkbox ticked, or use the py launcher which Windows installs automatically.
Another process — usually a stuck Odysseus AI from a previous run — is holding port 7000. Find the PID and kill it.
Some Python packages compile native code on Windows and need the Visual C++ build tools. Free download, ~3 GB, one-time install.
If you chose the WSL2 path, Windows needs the latest WSL kernel. Microsoft ships it via Windows Update, but it sometimes lags.
Your virtual environment isn't activated, or you installed dependencies into a different Python. Always activate the venv before running anything.
The diagnostic pattern-matches your error text against 12 known Windows-specific Odysseus AI install failures and surfaces the exact command sequence to fix it. Runs entirely in your browser — your log text never leaves your machine.
Copy the relevant error lines from PowerShell, paste below, and click match. The longer the snippet the better.
There are three legitimate ways to install Odysseus AI on Windows. None is universally best. Pick by your existing workflow, not by what sounds most impressive on Reddit.
docker compose// landfall checklist
http://localhost:7000 opens the Odysseus AI login screenOdysseus AI's speed depends almost entirely on the model and the backend, not the workspace itself. These four tweaks move the needle the most on Windows.
A model that exceeds your available RAM will spill to disk and grind to a halt. Rule of thumb on Windows: pick a quantized model whose file size is ~60% of your free RAM. 16 GB RAM → 7–8B model in Q4_K_M quantization (about 4.5 GB on disk, ~9 GB in memory). 32 GB RAM → 14B model. 64 GB RAM → 30B+ models become viable.
Ollama auto-detects NVIDIA GPUs on Windows. If you have an RTX card with 8 GB+ VRAM, Ollama will offload as many layers as fit into VRAM, leaving the rest on CPU. Confirm offload is working by watching ollama ps while a chat is running — you should see GPU memory listed.
Defender real-time scanning can add 30–50% overhead to Python startup and model load. In Windows Security → Virus & threat protection → Manage settings → Exclusions, add the odysseus folder and your .ollama models folder. Re-enable when you uninstall.
Ollama stores models in C:\Users\<you>\.ollama\models by default. If your C: drive is tight, set the OLLAMA_MODELS environment variable to point at a faster external NVMe. Restart Ollama from the system tray to apply.
winver to confirm your build number.Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass once in the current PowerShell session. This bypasses the policy for that window only — the change reverts the moment you close PowerShell. It's the safest fix because it doesn't change machine-wide policy.ollama pull llama3.2:1b) or use an API provider through Odysseus AI's OpenRouter / OpenAI settings instead.git pull to fetch new code, then re-run .\launch-windows.ps1 — the launcher detects new dependencies in requirements.txt and installs them. Your chat history, settings, and Ollama models survive the update.ipconfig, allow port 7000 in Windows Defender Firewall, then open http://<your-ip>:7000 from your phone. Do not expose this port to the public internet — use Tailscale or Cloudflare Access for remote access.odysseus folder. That's it — there are no registry entries, no system services, no Windows Add/Remove Programs entry. To also remove Ollama and downloaded models, uninstall Ollama from Settings → Apps, then delete C:\Users\<you>\.ollama.Odysseus AI is running on Windows. Here's where to go next based on what you want to do.