Install

There are three ways to install Fred. We strongly recommend uv — it ships its own Python and dodges every Python install bug you've ever seen. The other paths work, but you should only reach for them if you have a reason.

Recommended: uv

uv is a fast Python package manager that installs CLI tools into isolated environments and manages the Python interpreter for you. One install, one command, no system Python in the loop.

Pick the line for your OS:

# macOS
brew install uv

# Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Then install Fred as a uv-managed tool. This works identically on every OS:

uv tool install fredcode

That's it. fred is now on your PATH and uv has set up a private Python 3.13 for it. Skip to Verify the install.

One-liner installs

The uv install scripts above auto-detect the right binary, drop it in ~/.local/bin (Linux/macOS) or %USERPROFILE%\.local\bin (Windows), and add it to your shell's PATH. Open a new terminal after running them.

macOS

Several options on macOS. In rough order of "least likely to break":

  • uv (best) — see above. Works on Apple Silicon and Intel, ships its own Python.
  • pipx — also fine. Install with brew install pipx && pipx ensurepath, then pipx install fredcode.
  • Homebrew (direct) — there's no brew install fredcode formula yet. Coming soon. For now use uv.
  • pyenv users — pyenv global 3.13.x first, then pip install fredcode. You already know what you're doing.

macOS users get optional Keychain integration for the API key. Install with the [keychain] extra:

# with uv
uv tool install "fredcode[keychain]"

# with pipx
pipx install "fredcode[keychain]"

With the keychain extra, fred login mirrors the API key into your login keychain in addition to ~/.config/fred/credentials.json. The file is still the source of truth; the keychain is a convenience for tools that read from it.

Linux

Same priority order: uv, then pipx, then distro pip with care. Distro pip on Debian, Ubuntu 22.04+, Fedora 38+, and most modern distros refuses to install into the system site-packages thanks to PEP 668. That's a feature.

# uv (best, works on every distro)
curl -LsSf https://astral.sh/uv/install.sh | sh
uv tool install fredcode

# pipx (apt/yum)
sudo apt install pipx        # Debian/Ubuntu
sudo dnf install pipx        # Fedora
pipx ensurepath
pipx install fredcode

# Distro pip with --user (last resort)
python3 -m pip install --user fredcode
apt/yum pip will refuse

If you see error: externally-managed-environment, that's PEP 668 doing its job. Don't fight it with --break-system-packages. Use uv or pipx — both install Fred into an isolated environment without touching the system Python.

Windows

uv is the cleanest path on Windows. Install via winget or the PowerShell one-liner:

# winget
winget install --id=astral-sh.uv -e

# or PowerShell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# then
uv tool install fredcode

If you want pipx instead, install Python from python.org (3.11+), then:

python -m pip install --user pipx
python -m pipx ensurepath
pipx install fredcode

WSL2 users — install Fred inside the WSL distro using the Linux instructions above. Don't bridge a Windows install into WSL or vice versa; pick one home.

Windows Terminal vs cmd.exe

Fred renders streaming output and Unicode prompts. Windows Terminal handles both fine; the legacy cmd.exe may garble box-drawing characters. If your terminal mangles the spinner or status line, run with --no-stream for non-streaming output, or switch to Windows Terminal / PowerShell 7.

Verify the install

fred --version
# fred 0.2.1 (or newer)

fred login
# opens browser, writes ~/.config/fred/credentials.json

fred whoami
# you@example.com  ·  balance: $1.00  ·  key: fck_…7a2b

If fred --version prints anything below 0.2.1, your PATH is picking up an old install. Find it with which fred (Linux/macOS) or where fred (Windows) and uninstall the stale copy.

Upgrading

Two ways to upgrade, depending on how you installed.

# uv
uv tool upgrade fredcode

# pipx
pipx upgrade fredcode

# or use the built-in subcommand (works regardless of installer)
fred update

fred update detects how you installed, runs the right upgrade command, and re-launches Fred against the new version. Useful flags:

  • fred update --check — print the latest version and exit, no install.
  • fred update --no-run — upgrade but don't re-launch the REPL.

Optional extras

Pip extras you can opt into with bracket syntax:

  • fredcode[telemetry] — adds psycopg for self-hosted Postgres telemetry. See /docs/telemetry.
  • fredcode[keychain] — adds keyring so fred login mirrors the API key to the macOS Keychain.
uv tool install "fredcode[telemetry,keychain]"
# or
pipx install "fredcode[telemetry,keychain]"

Editable dev install

For contributors hacking on Fred itself. Clone the repo and install in editable mode against a Python 3.13 venv:

git clone https://github.com/fredcode/fred.git
cd fred
python3.13 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev,telemetry]"

# verify
fred --version
pytest

On Windows, swap source .venv/bin/activate for .venv\Scripts\Activate.ps1.

If pip install fails with PEP 668

Errors like externally-managed-environment mean your system Python forbids global pip installs — which is correct. Don't override it with --break-system-packages. Use uv or pipx instead — neither hits this issue. See Troubleshooting if you're stuck.

Next

Getting started — log in and run your first session. Models — pick between flash and pro.