lychee

Lychee finds broken hyperlinks and mail addresses inside Markdown, HTML, reStructuredText, or any other text file or website.

Core Functionality

Lychee helps at finding and validating links across multiple file formats and websites. It supports Markdown files (.md, .mkd, .mdx, .markdown), HTML files (.html, .htm), plain text files, reStructuredText documents, and can crawl entire websites. The tool can even process EPUB files when used with atool, making it versatile for various documentation and content workflows.

Advanced Link Checking

To speed up the process, lychee uses async and parallel processing to check links efficiently. It handles HTTP/HTTPS links with full redirect support, validates email addresses through SMTP verification, and can check fragments and anchors within pages. The tool resolves relative URLs with configurable base URL support and handles modern web features like chunked encoding and GZIP compression.

Powerful Configuration Options

Filtering and Pattern Matching:

• Include/exclude patterns with regex support
• File globbing with advanced pattern matching
• Private IP exclusion (private, link-local, loopback ranges)
• Status code filtering with range syntax (200..=299)

Authentication and Headers:

• Custom headers and user agents
• Basic authentication support
• GitHub token integration for rate limit avoidance
• Cookie jar support for session-based sites

Performance Tuning:

• Request caching with configurable duration
• Retry logic with exponential backoff
• Concurrent processing with customizable limits
• TLS version control and insecure SSL handling

Output and Integration

Lychee provides multiple output formats including JSON, Markdown, compact, and detailed reports. The terminal output features colored text and emoji support for better readability, while progress bars keep you informed during long-running checks. Integration options include GitHub Actions, pre-commit hooks, Docker containers, and direct library usage for Rust projects.

Use Cases

• Documentation maintenance - Keep documentation links up-to-date
• Website validation - Ensure all website links are functional
• CI/CD integration - Automated link checking in build pipelines
• Content auditing - Regular link health monitoring
• Migration verification - Validate links after site migrations
• SEO optimization - Identify and fix broken external links

Command Examples

# Check all files in current directory
lychee .

# Check specific files
lychee README.md docs/

# Check a website
lychee https://example.com

# Offline mode (local files only)
lychee --offline docs/

# Exclude patterns
lychee --exclude "example\.(com|org)" .

# Custom output format
lychee --format json --output report.json .

# With caching for faster subsequent runs
lychee --cache .