Install Indexly – Setup, Configuration & First Run

Indexly runs on Windows, macOS, and Linux.

For most users:

• Use Homebrew on macOS/Linux
• Use pip on Windows

1. Install on macOS/Linux with Homebrew (Recommended)

brew tap kimsgent/indexly
brew install indexly

Verify:

indexly --version
indexly --help

No manual PYTHONPATH wrapper is required for current Homebrew releases.

If brew is already installed on Linux but not available in the current shell, initialize Homebrew first:

eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)"

2. Install on Windows with pip (Recommended)

py -m pip install --upgrade pip
py -m pip install indexly

Verify:

indexly --version
indexly --help

If the indexly command is not found immediately, restart the terminal and run again.

3. Cross-platform pip install (Alternative)

python -m pip install --upgrade pip
python -m pip install indexly

Verify:

indexly --version

4. Optional Feature Packs

Indexly ships with a lightweight core install. Add extras only when needed:

python -m pip install "indexly[documents]"
python -m pip install "indexly[analysis]"
python -m pip install "indexly[visualization]"
python -m pip install "indexly[pdf_export]"
python -m pip install "indexly[backup]"

Install all optional groups:

python -m pip install "indexly[documents,analysis,visualization,pdf_export,backup]"

5. First Run

indexly index /path/to/folder
indexly search "invoice"
indexly regex "[A-Z]{3}-\\d{4}"

6. Upgrade and Uninstall

Upgrade:

# pip
python -m pip install --upgrade indexly

# brew
brew upgrade indexly

Uninstall:

# pip
python -m pip uninstall indexly

# brew
brew uninstall indexly

7. Developer Setup (All Platforms)

git clone https://github.com/kimsgent/project-indexly.git
cd project-indexly
python -m venv .venv

Activate:

• macOS/Linux: source .venv/bin/activate
• Windows (PowerShell): .venv\Scripts\Activate.ps1

Install editable package with optional extras:

python -m pip install --upgrade pip
python -m pip install -e ".[documents,analysis,visualization,pdf_export,backup]"
python -m pip install pytest pytest-cov flake8 black isort mypy build twine

Verify:

indexly --help

On Windows, contributors can also use the repo-native bootstrap script:

.\setup.ps1 -CheckOnly
.\setup.ps1

8. Troubleshooting

• indexly: command not found
  • Restart terminal.
  • Confirm install succeeded (pip show indexly or brew list indexly).
• Missing feature message (for example analysis/documents)
  • Install the matching extra group from section 4.
• Homebrew on Linux not detected
  • Run eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)" and retry.
• Need a quick environment check
  • Run indexly doctor.

Indexly is now ready to use.

See also Windows Development Environment Setup, Linux Development Environment Setup, and Indexly Developer Guide.