Skip to content

Installation

patterndb-yaml 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

patterndb-yaml 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 patterndb-yaml.

patterndb-yaml works on Linux, macOS, and Windows (via WSL2).

brew tap jeffreyurban/patterndb-yaml
brew install patterndb-yaml

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 patterndb-yaml

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

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 patterndb-yaml

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

Via Source

For development or the latest unreleased features:

git clone https://github.com/JeffreyUrban/patterndb-yaml.git
cd patterndb-yaml
pip install .

This installs patterndb-yaml and its dependencies:

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

Development Installation

For contributing or modifying patterndb-yaml, install in editable mode with development dependencies:

git clone https://github.com/JeffreyUrban/patterndb-yaml.git
cd patterndb-yaml
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/patterndb-yaml && brew install patterndb-yaml
  • pipx: pipx install patterndb-yaml
  • pip: pip install patterndb-yaml

Virtual Environments

If using pip directly, consider using a virtual environment: 

python3 -m venv venv
source venv/bin/activate
pip install patterndb-yaml

macOS

Recommended installation methods:

  • Homebrew: brew tap jeffreyurban/patterndb-yaml && brew install patterndb-yaml (recommended)
  • pipx: pipx install patterndb-yaml
  • pip: pip install patterndb-yaml

Windows

Recommended installation methods:

  • pipx: pipx install patterndb-yaml (recommended)
  • pip: pip install patterndb-yaml

The patterndb-yaml command will be available in your terminal after installation.

Verify Installation

After installation, verify patterndb-yaml is working:

patterndb-yaml --version
patterndb-yaml --help

Try a quick test with the --generate-xml option:

echo "rules: []" | patterndb-yaml --rules /dev/stdin --generate-xml

This should output valid syslog-ng XML pattern database markup.

Upgrading

Homebrew

brew upgrade patterndb-yaml

pipx

pipx upgrade patterndb-yaml

pip

pip install --upgrade patterndb-yaml

Source Installation

cd patterndb-yaml
git pull
pip install --upgrade .

For development installations:

cd patterndb-yaml
git pull
pip install --upgrade -e ".[dev]"

Uninstalling

Homebrew

brew uninstall patterndb-yaml

pipx

pipx uninstall patterndb-yaml

pip

pip uninstall patterndb-yaml

Troubleshooting

Command Not Found

If patterndb-yaml command is not found after installation:

  1. Check pip installed in the right location: 

    pip show patterndb-yaml

  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 patterndb-yaml --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