> ## Documentation Index
> Fetch the complete documentation index at: https://lunr-f6858e75.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation

> Install HelixCommit on your system

## Requirements

<CardGroup cols={3}>
  <Card title="Python 3.9+" icon="python" color="#0A6ACB">
    Required runtime environment
  </Card>

  <Card title="Git" icon="code-branch" color="#F26419">
    Must be installed and in PATH
  </Card>

  <Card title="pip" icon="box" color="#F6A02D">
    Python package manager
  </Card>
</CardGroup>

Verify your Python version:

```bash theme={}
python --version
```

<Info>
  HelixCommit works on **macOS**, **Linux**, and **Windows**. Git must be installed and accessible in your system PATH.
</Info>

***

## Install via pip

The simplest way to install HelixCommit is using pip from PyPI.

```bash theme={}
pip install helixcommit
```

<Check>
  After installation, verify that HelixCommit is available by running `helixcommit --help`
</Check>

***

## Using a virtual environment

You should install HelixCommit in a virtual environment to avoid conflicts with other Python packages.

<Tabs>
  <Tab title="venv">
    ```bash theme={}
    # Create a virtual environment
    python -m venv .venv

    # Activate the virtual environment
    source .venv/bin/activate  # On macOS/Linux
    # or
    .venv\Scripts\activate  # On Windows

    # Install HelixCommit
    pip install helixcommit
    ```
  </Tab>

  <Tab title="conda">
    ```bash theme={}
    # Create a conda environment
    conda create -n helixcommit python=3.11

    # Activate the environment
    conda activate helixcommit

    # Install HelixCommit
    pip install helixcommit
    ```
  </Tab>

  <Tab title="pipx">
    ```bash theme={}
    # Install with pipx for isolated CLI tool
    pipx install helixcommit

    # Verify installation
    helixcommit --version
    ```

    <Tip>
      Using `pipx` is ideal for installing HelixCommit as a standalone CLI tool without managing virtual environments.
    </Tip>
  </Tab>
</Tabs>

***

## Install from source

You can install the latest development version directly from GitHub.

### Clone and install

```bash theme={}
# Clone the repository
git clone https://github.com/bjornefisk/helixcommit.git
cd helixcommit

# Create and activate virtual environment
python -m venv .venv
source .venv/bin/activate

# Install in editable mode
pip install -e .
```

<Info>
  Installing in editable mode with `-e` allows you to modify the source code and see changes immediately without reinstalling.
</Info>

### Install development dependencies

If you plan to contribute or run tests, install the development dependencies:

```bash theme={}
pip install -e ".[dev]"
```

This installs additional packages for testing, linting, and type checking:

| Package    | Purpose                     |
| ---------- | --------------------------- |
| pytest     | Running tests               |
| ruff       | Code formatting and linting |
| mypy       | Static type checking        |
| pytest-cov | Coverage reports            |

***

## Verify installation

After installing HelixCommit, verify that it works correctly.

<Steps>
  <Step title="Check the version" icon="hashtag">
    Run the following command to display the installed version:

    ```bash theme={}
    helixcommit --version
    ```

    Expected output will show the installed HelixCommit version, for example:

    ```
    helixcommit, version 1.1.0
    ```
  </Step>

  <Step title="Display help information" icon="circle-question">
    Verify all commands are available:

    ```bash theme={}
    helixcommit --help
    ```

    You should see a list of available commands and options.
  </Step>

  <Step title="Generate your first release notes" icon="play">
    Navigate to any Git repository and run:

    ```bash theme={}
    helixcommit generate --unreleased --no-prs --format markdown
    ```

    <Check>
      If you see release notes output, HelixCommit is installed correctly and ready to use!
    </Check>
  </Step>
</Steps>

***

## Optional dependencies

HelixCommit includes optional features that require additional dependencies.

### GitHub integration

GitHub integration is included by default through the `PyGithub` package. To use it, you need a GitHub personal access token:

```bash theme={}
export GITHUB_TOKEN=your_github_token_here
```

<Tip>
  Create a GitHub token at [github.com/settings/tokens](https://github.com/settings/tokens) with `repo` scope for private repositories or no special permissions for public repositories.
</Tip>

### AI summarization

AI features require API keys from supported providers:

<Tabs>
  <Tab title="OpenAI">
    ```bash theme={}
    export OPENAI_API_KEY=sk-...

    helixcommit generate --unreleased --use-llm --openai-model gpt-4o-mini
    ```

    Get your API key from [platform.openai.com/api-keys](https://platform.openai.com/api-keys)
  </Tab>

  <Tab title="OpenRouter">
    ```bash theme={}
    export OPENROUTER_API_KEY=sk-or-...

    helixcommit generate --unreleased --use-llm --llm-provider openrouter
    ```

    Get your API key from [openrouter.ai](https://openrouter.ai)

    <Info>
      OpenRouter provides access to multiple AI models, including free options like `meta-llama/llama-3.3-70b-instruct:free`
    </Info>
  </Tab>
</Tabs>

### ChromaDB for advanced RAG

For advanced retrieval-augmented generation (RAG) features, install ChromaDB:

```bash theme={}
pip install chromadb
```

Then use the `chroma` backend when generating summaries:

```bash theme={}
helixcommit generate --unreleased --use-llm --rag-backend chroma
```

***

## Updating HelixCommit

Keep HelixCommit up to date to access the latest features and bug fixes.

### Update from PyPI

```bash theme={}
pip install --upgrade helixcommit
```

### Update from source

```bash theme={}
cd helixcommit
git pull origin main
pip install -e ".[dev]"
```

***

## Uninstalling

To remove HelixCommit from your system:

```bash theme={}
pip uninstall helixcommit
```

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Command not found after installation" icon="magnifying-glass">
    If `helixcommit` is not found after installation, ensure that Python's scripts directory is in your PATH.

    ```bash theme={}
    # On macOS/Linux
    export PATH="$HOME/.local/bin:$PATH"

    # On Windows (PowerShell)
    $env:Path += ";$HOME\AppData\Local\Programs\Python\Python3XX\Scripts"
    ```

    Add this to your shell configuration file (`.bashrc`, `.zshrc`, etc.) to make it permanent.
  </Accordion>

  <Accordion title="Permission denied errors" icon="lock">
    If you encounter permission errors during installation:

    ```bash theme={}
    # Install for current user only
    pip install --user helixcommit

    # Or use a virtual environment (recommended)
    python -m venv .venv
    source .venv/bin/activate
    pip install helixcommit
    ```
  </Accordion>

  <Accordion title="SSL certificate errors" icon="shield-halved">
    If you see SSL certificate errors when installing:

    ```bash theme={}
    pip install --trusted-host pypi.org --trusted-host files.pythonhosted.org helixcommit
    ```

    <Warning>
      Only use this workaround if absolutely necessary. It's better to fix the underlying SSL certificate issue on your system.
    </Warning>
  </Accordion>

  <Accordion title="Git not found" icon="code-branch">
    HelixCommit requires Git to be installed and accessible. Install Git for your operating system:

    | Platform      | Command                                          |
    | ------------- | ------------------------------------------------ |
    | macOS         | `brew install git`                               |
    | Debian/Ubuntu | `sudo apt install git`                           |
    | RHEL/CentOS   | `sudo yum install git`                           |
    | Windows       | Download from [git-scm.com](https://git-scm.com) |

    Verify Git is installed:

    ```bash theme={}
    git --version
    ```
  </Accordion>
</AccordionGroup>

***

## Next steps

<CardGroup cols={2}>
  <Card title="Quick start guide" icon="rocket" href="/quickstart" color="#F26419">
    Generate your first release notes in minutes
  </Card>

  <Card title="CLI reference" icon="terminal" href="/cli-reference" color="#0A6ACB">
    Explore all available commands and options
  </Card>
</CardGroup>