How to Troubleshoot Kimi-CLI Installation Issues: A Complete Guide

Most Kimi-CLI installation failures stem from missing uv prerequisites, incompatible Python versions below 3.12, or undetected Git-Bash paths on Windows, all of which can be diagnosed by inspecting environment variables and the validation logic in the MoonshotAI source code.

Kimi-CLI is a Python-based terminal AI agent developed by MoonshotAI that relies on the uv package manager for installation and runtime environment detection. When you troubleshoot kimi-cli installation issues, understanding the five-stage validation pipeline—from prerequisite checks to platform-specific shell detection—allows you to pinpoint exactly where the process fails.

Understanding the Kimi-CLI Installation Pipeline

The installation process follows a strict sequence defined in the repository source code. Each stage performs specific validations that generate distinct error messages when requirements are not met.

Prerequisite Validation via install.sh

The installation begins with scripts/install.sh, which verifies that uv is present on your system. If uv is missing, the script automatically downloads and installs it before proceeding. This script serves as the entry point for all installation methods and must complete successfully before package installation begins.

UV Tool Installation Process

Once uv is available, the actual package installation occurs via uv tool install kimi-cli (or uv tool install --python <version> kimi-cli for specific Python versions). This command builds a wheel from the source and installs it into ~/.local/bin, creating an isolated environment for the CLI tool. The tool requires Python 3.12, 3.13, or 3.14 to build correctly.

Runtime Environment Detection

After installation, the runtime immediately executes platform detection logic located in src/kimi_cli/utils/environment.py. The Environment.detect() method identifies your operating system and selects the appropriate shell interface. On Windows systems, this triggers a specific search sequence for Git-Bash that must locate bash.exe to enable shell tool functionality.

Windows Git-Bash Resolution Logic

For Windows users, the _find_git_bash_path() function in environment.py executes a hierarchical discovery process:

1. Checks the KIMI_CLI_GIT_BASH_PATH environment variable
2. Executes where.exe git to locate the Git binary
3. Runs git --exec-path to derive the installation directory
4. Searches common installation locations (e.g., C:\Program Files\Git\bin\bash.exe)

If all methods fail, the code raises a GitBashNotFoundError along with the _GIT_BASH_INSTALL_HINT message providing specific remediation steps.

Resolving Common Installation Failures

Specific error symptoms correspond to distinct failure points in the installation pipeline. Use the following targeted solutions based on your error message.

Missing UV Package Manager

If you encounter "uv command not found," the prerequisite check failed. Run the official installer script which handles uv installation automatically:

curl -LsSf https://code.kimi.com/install.sh | bash

Alternatively, install uv manually following the Astral documentation, then verify it appears in your $PATH.

Python Version Compatibility Errors

The error "No matching distribution found" indicates you are using an incompatible Python version (older than 3.12) or missing build dependencies. Specify a supported Python version explicitly during installation:

uv tool uninstall kimi-cli
uv tool install --python 3.13 kimi-cli

Supported versions are 3.12, 3.13, and 3.14. Avoid Python 3.11 or earlier as they lack required language features.

Git-Bash Not Found on Windows

When the Shell tool raises GitBashNotFoundError, the _find_git_bash_path() function could not locate bash.exe. Install Git for Windows, then either add its bin directory to your system PATH or set the environment variable permanently:

[Environment]::SetEnvironmentVariable(
    "KIMI_CLI_GIT_BASH_PATH",
    "C:\Program Files\Git\bin\bash.exe",
    "User"
)

Verify the path points to an existing executable; incorrect paths will cause the same error during runtime.

PATH Configuration Problems

If the kimi command returns "command not found" after successful installation, the uv tool directory is not in your shell's $PATH. Add the following to your shell configuration file (e.g., ~/.bashrc, ~/.zshrc, or ~/.config/fish/config.fish):

export PATH="$HOME/.local/bin:$PATH"

Reload your shell or open a new terminal session for the change to take effect.

macOS Security Permissions

First-launch hangs on macOS indicate that security prompts are blocking execution. Grant your terminal application "Developer Tools" permission in System Settings → Privacy & Security → Developer Tools to allow the CLI to spawn subprocesses without manual intervention.

Diagnostic Scripts and Fixes

Use these code snippets to programmatically verify your environment before attempting reinstallation.

Verifying Git-Bash Availability

Run this Python script to test whether the Kimi-CLI environment detection logic can locate your Git-Bash installation:

import asyncio
from kimi_cli.utils.environment import _find_git_bash_path, GitBashNotFoundError

async def check_git_bash():
    try:
        bash_path = await _find_git_bash_path()
        print(f"Git-bash found at: {bash_path}")
    except GitBashNotFoundError as e:
        print(f"Error: {e}")

asyncio.run(check_git_bash())

Successful execution confirms that the src/kimi_cli/utils/environment.py logic will function correctly during CLI runtime.

Reinstalling with Specific Python Versions

For a clean reinstall targeting a specific Python interpreter:

uv tool uninstall kimi-cli
uv tool install --python 3.13 kimi-cli

This bypasses issues where uv might default to an incompatible system Python version.

Summary

• Prerequisites: Verify uv is installed via scripts/install.sh before attempting package installation.
• Python Versions: Use Python 3.12, 3.13, or 3.14; specify explicitly with --python if defaults fail.
• Windows Requirements: Install Git for Windows and ensure bash.exe is discoverable via PATH or KIMI_CLI_GIT_BASH_PATH.
• PATH Issues: Add $HOME/.local/bin to your shell configuration if the kimi command is not found.
• macOS Setup: Grant Developer Tools permissions to your terminal to prevent first-run hangs.
• Source References: Consult src/kimi_cli/utils/environment.py for platform detection logic and scripts/install.sh for prerequisite handling.

Frequently Asked Questions

Why does Kimi-CLI require Python 3.12 or higher?

The codebase utilizes language features and standard library improvements introduced in Python 3.12 that are not backward compatible with earlier versions. The pyproject.toml in the repository specifies these requirements, and the uv tool install command enforces them during the wheel build process.

How do I fix "Git for Windows not found" errors?

Install Git for Windows from the official distribution, then either ensure its bin directory is in your system PATH or set the KIMI_CLI_GIT_BASH_PATH environment variable to the absolute path of bash.exe. The detection logic in src/kimi_cli/utils/environment.py checks this variable before attempting automatic discovery.

What should I do if the kimi command is not found after installation?

This indicates that uv's tool installation directory (~/.local/bin) is not in your shell's executable path. Add export PATH="$HOME/.local/bin:$PATH" to your shell's rc file (such as ~/.bashrc or ~/.zshrc), then reload your shell configuration with source ~/.bashrc or open a new terminal window.

How can I verify that my environment is correctly configured before running Kimi?

Execute the diagnostic Python script that imports _find_git_bash_path from kimi_cli.utils.environment to verify Git-Bash detection on Windows, and run kimi --version to confirm the CLI is accessible and properly installed. If both succeed, run kimi followed by /login to complete the initial configuration.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}