简体中文
English
Website review
This review may include AI-generated content and is not individually verified. Domain, certificate and other facts come from the observed data on this page.
What is lychee?
lychee is a command-line link checker: it scans your files or a live site, follows the links it finds, and reports the ones that are broken. It's written in Rust, runs asynchronously, and ships as a single static binary, so there's no runtime to install or dependency chain to manage. It reads Markdown and HTML natively, and can emit structured JSON output.
Who it's for
- Docs and static-site maintainers — a README or docs folder full of relative links and external URLs is exactly the case it was built for.
- CI/CD pipelines — JSON output means a build step can fail the job and post a machine-readable list of failures.
- Large repositories — the async design matters when you have thousands of links rather than dozens.
How it compares to your alternatives
| Approach | Best when | Trade-off |
|---|---|---|
| lychee | You want one fast pass over many files or a whole site, with CI-friendly output | You install and run a separate tool |
| Editor or IDE link plugins | You want feedback while typing | Usually checks one file at a time, rarely covers a whole site |
| Manual spot-checking | The link set is tiny and rarely changes | Doesn't scale, and misses links buried in generated output |
A concrete next step
If you maintain a docs repo, try running lychee against your Markdown directory first and read the failure list before wiring it into CI. That one pass tells you whether the noise level (rate-limited sites, auth-walled pages that return errors to anonymous checkers) is low enough for a blocking build step, or whether you'd rather run it on a schedule and review results. For a hosted alternative aimed at scheduled site checks, see Dead Link Checker.
How do I install lychee on my system?
Install lychee by downloading its single static binary — the official docs recommend this as the simplest route, since there are no runtime dependencies to manage. The project also publishes packages through common system package managers, and you can build it from source with Rust's cargo if you prefer. Check the installation section of lychee for the exact commands for your platform.
Choosing your install method
| Method | Best for | Trade-off |
|---|---|---|
| Static binary download | Most users, quick setup | You update it yourself |
| System package manager | Keeping it current with other tools | Version may lag behind releases |
cargo install |
Rust developers, bleeding edge | Requires a Rust toolchain and compiles locally |
After installing, confirm it works by running lychee --version, then try a real check against a small folder of Markdown or HTML files before wiring it into CI. If you plan to use the JSON output for pipelines, run one test pass with that flag early so you can see the shape of the results before writing parsing logic.
Can lychee check links inside Markdown and HTML files?
Yes. lychee natively supports both Markdown and HTML files, so it can extract and check the links inside them without extra conversion steps.
What that means in practice
- Markdown: Useful for README files, docs folders, changelogs and static-site content. It can catch broken relative links, dead external URLs and malformed email addresses in your prose.
- HTML: Useful for built sites, templates and single-page output. It checks anchors and other link-bearing elements in the markup.
- Mixed repositories: You can point it at a directory and let it handle both formats together, which fits documentation repos that contain
.mdsources and generated.html.
How to decide if it fits your workflow
| Your situation | Why lychee suits it |
|---|---|
| Large docs or codebase with many links | Rust-based async checking is built for speed |
| CI/CD pipeline | Structured JSON output makes results machine-readable |
| Simple setup preferred | Distributed as a single static binary |
| Both Markdown and HTML in one repo | Native support for both formats |
Next step
Run it against a small folder first, for example your docs/ directory, and inspect the output before wiring it into CI. If you also maintain a website, compare the experience with a dedicated site checker such as Screaming Frog or a hosted service like W3C Validator for markup validation, since those focus on crawling live pages rather than local files.
A concrete scenario
A maintainer with a docs/ folder of Markdown files and a generated site/ folder of HTML can run one command over both, get a JSON report in CI, and fail the build only when a link is genuinely broken. That avoids maintaining two separate checking tools for the same repository.
How do I integrate lychee into a CI/CD pipeline?
Use lychee as a step that fails the build when it finds broken links, and have it emit JSON so your pipeline can archive or post-process the results. The site describes it as an async, Rust-based checker with native Markdown/HTML support, a single static binary, and structured JSON output — all of which suit CI runners.
Typical CI/CD pattern
- Install the static binary (or use a container image) in the job.
- Run lychee against your docs, site output, or repository files.
- Let a non-zero exit code fail the pipeline; capture JSON as a build artifact.
- Optionally publish a summary to the pull request or chat.
Concrete example (GitHub Actions-style, illustrative)
- name: Check links
run: lychee --format json --output lychee-report.json ./docs
- name: Upload report
if: always()
uses: actions/upload-artifact@v4
with:
name: lychee-report
path: lychee-report.json
Adapt the path (./docs, ./public, or specific files) to what you actually publish. The --format json flag aligns with the JSON output the site advertises.
What to decide before wiring it in
| Decision | Why it matters |
|---|---|
| Check built HTML or source Markdown? | Built output catches rendered links; source is faster and catches issues earlier. |
| Fail the build or warn only? | Failing enforces link hygiene but can block merges on flaky external sites. |
| Check external links every run? | External sites are slow and rate-limit; many teams schedule those separately. |
| Where to store JSON? | Artifacts or a PR comment make failures actionable. |
Practical cautions
External link checks are the main source of false failures: sites go down, block bots, or rate-limit. Consider running internal-link checks on every commit and external checks on a schedule or nightly job. If lychee supports config files or ignore lists in your version, keep excluded hosts and known-flaky URLs there rather than in the pipeline script.
Next step
Run lychee locally once with JSON output to see the report shape, then copy that exact command into your CI job. Start with internal links only, confirm the pipeline fails correctly on a deliberately broken link, then add external checks on a schedule.
For the authoritative flag names and installation options, see lychee.
How do I configure lychee to ignore or exclude certain links?
Lychee supports excluding links through configuration rather than by editing each file. The two main mechanisms are an exclude pattern list (for matching URLs or paths you never want checked) and an exclude file (a text file of URLs to skip). Patterns are typically regular expressions, so example\.com matches that domain anywhere in a URL. You can also exclude by file path or by link text depending on the flag you use.
The practical distinction matters:
- Exclude by URL pattern — best when a whole domain, subdomain, or URL fragment is unreliable (rate-limited hosts, staging domains, tracking redirects).
- Exclude by file — best when you have a long, changing list of known-bad or intentionally dead links you want to maintain separately from your config.
- Exclude mail addresses — useful if your docs contain placeholder addresses that will never resolve.
Where the settings go
Lychee reads a config file (commonly lychee.toml or lychee.toml referenced via a flag) and also accepts the same options as command-line flags. Typical keys look like exclude, exclude_file, and exclude_mail, and you can point to the config with a --config flag. If you only need a one-off run, passing the exclude flag directly on the command line is simpler than creating a file.
A concrete scenario
Suppose you maintain a documentation site with links to an internal staging server and a few partner sites that block automated requests. You would:
- Add a regex for the staging host and the partner domains to
exclude. - Put any one-off dead links in an
exclude_fileso contributors can add to it without touching the main config. - Run lychee in CI with JSON output so failures are reported as structured results rather than raw text.
Trade-offs to weigh
Excluding too broadly hides real breakage — a pattern like .* defeats the purpose. Prefer the narrowest pattern that matches the problem host or path. Also remember that excluded links are silently skipped, so keep the exclude list small and reviewed, and consider a comment or naming convention in the file to record why each entry exists.
Next step
Run lychee --help to confirm the exact flag names for your installed version, then start with a single --exclude pattern and expand only when a link genuinely cannot be checked. The project documentation is at lychee.
What are the performance limits of lychee for very large websites?
Lychee is built to stay fast on large sites because it checks links asynchronously and runs as a single static binary, but the page itself doesn't publish hard performance limits. In practice, throughput depends on how many concurrent requests you allow, how slow the target servers are, and how many links you're checking.
What the site actually claims
- Async, Rust-powered design aimed at speed for large projects.
- Native support for Markdown and HTML files.
- Structured JSON output for CI/CD integration.
Where limits usually show up
- Network latency and rate limits: Even with async checking, a remote server can throttle or time out, so total runtime is often bounded by the slowest external hosts, not by lychee itself.
- Concurrency settings: Higher parallelism finishes faster but risks overwhelming targets or triggering blocks; lower settings are safer but slower.
- Local resource use: A single static binary keeps installation simple, but memory and CPU still scale with the number of links and concurrent connections.
- CI time budgets: JSON output helps you automate checks, but a very large site may need to be split into scoped runs to fit within pipeline time limits.
Practical next step If you're checking a large documentation site, start with a moderate concurrency level and exclude or retry known slow domains, then measure wall-clock time on a representative subset before running the full site. For a broader comparison of link-checking approaches, see GitHub for lychee's repository and issues, where maintainers and users often discuss large-scale behavior.
DigitalOcean
Fastly
User reviews (0)