Skip to content

Installation

tui-delta can be installed via Homebrew, pipx, pip, or from source.

Requirements

  • Python 3.9 or higher (for pip/pipx installations)
  • Homebrew (for macOS/Linux Homebrew installation - automatically installs syslog-ng)
  • syslog-ng 4.10.1+ (for pattern matching engine)

syslog-ng Dependency

tui-delta requires syslog-ng to be installed. See the syslog-ng Installation Guide for platform-specific instructions.

Homebrew users: syslog-ng is installed automatically as a dependency.

pip/pipx users: You must install syslog-ng separately from official repositories before using tui-delta.

tui-delta works on Linux, macOS, and Windows (via WSL2).

brew tap jeffreyurban/tui-delta
brew install tui-delta

Automatically installs syslog-ng as a dependency. Homebrew manages all dependencies and provides easy updates via brew upgrade.

Via pipx (Cross-platform)

Install syslog-ng first

Before using pipx, you must install syslog-ng from official repositories. See syslog-ng Installation Guide for detailed instructions.

# After installing syslog-ng (see link above):
pipx install tui-delta

pipx installs in an isolated environment with global CLI access. Works on macOS, Linux, and Windows. Update with pipx upgrade tui-delta.

Via pip

Install syslog-ng first

Before using pip, you must install syslog-ng from official repositories. See syslog-ng Installation Guide for detailed instructions.

# After installing syslog-ng (see link above):
pip install tui-delta

Use pip if you want to use tui-delta as a library in your Python projects.

Via Source

For development or the latest unreleased features:

git clone https://github.com/JeffreyUrban/tui-delta.git
cd tui-delta
pip install .

This installs tui-delta and its dependencies:

  • typer - CLI framework
  • rich - Terminal formatting and progress display
  • pyyaml - YAML parsing

Development Installation

For contributing or modifying tui-delta, install in editable mode with development dependencies:

git clone https://github.com/JeffreyUrban/tui-delta.git
cd tui-delta
pip install -e ".[dev]"

Development dependencies include:

  • pytest - Test framework
  • pytest-cov - Code coverage
  • ruff - Linting and formatting
  • mypy - Type checking
  • types-pyyaml - Type stubs for YAML
  • pre-commit - Git hooks for code quality

Platform-Specific Notes

Linux

Recommended installation methods:

  • Homebrew: brew tap jeffreyurban/tui-delta && brew install tui-delta
  • pipx: pipx install tui-delta
  • pip: pip install tui-delta

Virtual Environments

If using pip directly, consider using a virtual environment: 

python3 -m venv venv
source venv/bin/activate
pip install tui-delta

macOS

Recommended installation methods:

  • Homebrew: brew tap jeffreyurban/tui-delta && brew install tui-delta (recommended)
  • pipx: pipx install tui-delta
  • pip: pip install tui-delta

Windows

Recommended installation methods:

  • pipx: pipx install tui-delta (recommended)
  • pip: pip install tui-delta

The tui-delta command will be available in your terminal after installation.

Verify Installation

After installation, verify tui-delta is working:

tui-delta --version
tui-delta --help

Upgrading

Homebrew

brew upgrade tui-delta

pipx

pipx upgrade tui-delta

pip

pip install --upgrade tui-delta

Source Installation

cd tui-delta
git pull
pip install --upgrade .

For development installations:

cd tui-delta
git pull
pip install --upgrade -e ".[dev]"

Uninstalling

Homebrew

brew uninstall tui-delta

pipx

pipx uninstall tui-delta

pip

pip uninstall tui-delta

Troubleshooting

Command Not Found

If tui-delta command is not found after installation:

  1. Check pip installed in the right location: 

    pip show tui-delta

  2. Verify Python scripts directory is in PATH: 

    python -m site --user-base
    Add <user-base>/bin to your PATH if needed.

  3. Use Python module syntax: 

    python -m tui-delta --help

Import Errors

If you see import errors, ensure dependencies are installed:

pip install typer rich

Or reinstall with dependencies:

pip install --force-reinstall .

Permission Errors

If you encounter permission errors, install for your user only:

pip install --user .

Or use a virtual environment (recommended):

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install .

Next Steps