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

> Troubleshoot Kimi-CLI installation issues with our comprehensive guide. Learn to fix uv prerequisites, Python version conflicts, and Git-Bash path errors for MoonshotAI kimi-cli.

- Repository: [Moonshot AI/kimi-cli](https://github.com/MoonshotAI/kimi-cli)
- Tags: how-to-guide
- Published: 2026-07-19

---

**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`](https://github.com/MoonshotAI/kimi-cli/blob/main/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`](https://github.com/MoonshotAI/kimi-cli/blob/main/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`](https://github.com/MoonshotAI/kimi-cli/blob/main/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:

```bash
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:

```bash
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:

```powershell
[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`):

```bash
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:

```python
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`](https://github.com/MoonshotAI/kimi-cli/blob/main/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:

```bash
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`](https://github.com/MoonshotAI/kimi-cli/blob/main/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`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/utils/environment.py) for platform detection logic and [`scripts/install.sh`](https://github.com/MoonshotAI/kimi-cli/blob/main/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`](https://github.com/MoonshotAI/kimi-cli/blob/main/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`](https://github.com/MoonshotAI/kimi-cli/blob/main/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.