Installation¶

Requirements¶

Python 3.10 or higher
pip or uv package manager

Basic Installation¶

Install JoyfulJay from PyPI:

Bash

pip install joyfuljay
# or
uv pip install joyfuljay

Optional Dependencies¶

JoyfulJay has several optional dependency groups for different use cases.

Fast Parsing¶

For improved parsing performance with dpkt (10x faster for large PCAPs):

Bash

pip install joyfuljay[fast]

High-Speed Capture¶

For high-speed live capture with libpcap:

Bash

pip install joyfuljay[libpcap]

Note: This requires libpcap development headers on your system.

Kafka Streaming¶

For streaming features to Apache Kafka:

Bash

pip install joyfuljay[kafka]

See Kafka Streaming Documentation for usage details.

Prometheus Metrics¶

For exporting processing metrics to Prometheus:

Bash

pip install joyfuljay[monitoring]

See Monitoring Documentation for usage details.

mDNS Discovery¶

For automatic server discovery on local networks:

Bash

pip install joyfuljay[discovery]

See Remote Capture Documentation for usage details.

Connection Graphs¶

For network graph analysis with NetworkX:

Bash

pip install joyfuljay[graphs]

PostgreSQL Database¶

For direct database insertion:

Bash

pip install joyfuljay[db]

Multiple Extras¶

Install multiple extras at once:

Bash

pip install joyfuljay[fast,kafka,monitoring,discovery,graphs]

Development¶

For development and testing (includes hypothesis, pytest, mypy, ruff):

Bash

pip install joyfuljay[dev]

Installation from Source¶

Clone the repository and install in development mode:

Bash

git clone https://github.com/cenab/joyfuljay.git
cd joyfuljay
pip install -e ".[dev]"

Verifying Installation¶

After installation, verify JoyfulJay is working:

Bash

jj --version

Or in Python:

Python

import joyfuljay
print(joyfuljay.__version__)

Platform-Specific Setup¶

Windows¶

Live capture requires Npcap:

Download Npcap from https://npcap.com/
Run the installer (check "Install in WinPcap API-compatible mode")
Restart your terminal/IDE

Check your setup:

Bash

jj status

Note: PCAP file processing works without Npcap.

macOS¶

Live capture works out of the box with the built-in libpcap.

For permissions, either: - Run with sudo: sudo jj live en0 -d 10 - Or grant Terminal network access in System Preferences → Security & Privacy → Privacy → Network

Linux¶

Live capture requires libpcap (usually pre-installed).

For permissions, either: - Run as root: sudo jj live eth0 -d 10 - Or add capture capability: sudo setcap cap_net_raw+ep $(which python)

Checking Your Setup¶

Run the status command to verify everything works:

Bash

jj status

Example output:

Text Only

JoyfulJay v0.1.0
Platform: Darwin 23.0.0
Python: 3.11.5

Live capture: [OK] libpcap available (5 interfaces)

Available interfaces:
  - en0
  - lo0
  - utun0

PCAP file processing: [OK] Always available

Troubleshooting¶

Scapy Import Errors¶

If you see Scapy-related errors, ensure Scapy is properly installed:

Bash

pip install scapy>=2.5.0

Permission Denied on Live Capture¶

Ensure you have appropriate privileges for network capture. On Linux:

Bash

sudo jj live eth0 --duration 10

Missing libpcap¶

If using the [libpcap] extra and encountering build errors, install libpcap:

Ubuntu/Debian: sudo apt-get install libpcap-dev
macOS: brew install libpcap
RHEL/CentOS: sudo yum install libpcap-devel