Skip to content
lychee Logo Docs

Getting Started

You can install Lychee using various package managers.

Terminal window
pacman -S lychee

Pre-built binaries

Section titled “Pre-built binaries”

Lychee provides binaries for Linux, macOS, and Windows for every release. You can download them from the releases page.

Docker

Section titled “Docker”

Lychee provides a handy official image over at lycheeverse/lychee, which is updated on every release.

To check files on your local machine, you need to mount them into the Docker container.

Here’s how to do that:

Terminal window
docker run --init -it -v `pwd`:/input lycheeverse/lychee /input/README.md

The --init parameter is passed so that lychee can be stopped from the terminal. We also pass -it to start an interactive terminal, which is required to show the progress bar.

Cargo

Section titled “Cargo”

Build dependencies

Section titled “Build dependencies”

On APT/dpkg-based Linux distros (e.g. Debian, Ubuntu, Linux Mint and Kali Linux) the following commands will install all required build dependencies, including the Rust toolchain and cargo:

Terminal window
curl -sSf '<https://sh.rustup.rs>' | sh
apt install gcc pkg-config libc6-dev libssl-dev

Compile and install lychee

Section titled “Compile and install lychee”
Terminal window
cargo install lychee

Feature flags

Section titled “Feature flags”

Lychee supports several feature flags:

  • native-tls enables the platform-native TLS crate native-tls.
  • vendored-openssl compiles and statically links a copy of OpenSSL. See the corresponding feature of the openssl crate.
  • rustls-tls enables the alternative TLS crate rustls.
  • email-check enables checking email addresses using the check-if-email-exists crate. This feature requires the native-tls feature.
  • check_example_domains allows checking example domains such as example.com. This feature is useful for testing.

By default, native-tls and email-check are enabled.

Usage

Section titled “Usage”

Lets get a quick overview of how to use Lychee in your project.

Section titled “Check All Links In Current Directory”

The following command recursively checks all links in all supported files inside the current directory.

Terminal window
lychee .

This traverses all subdirectories and checks the links in all files which lychee supports, such as .md, .html, and more.

Section titled “Check All Links On A Website”
Terminal window
lychee https://example.com

This command checks all links on the website https://example.com. It is not recursive and only checks the links on the given page. Recursion is currently not supported. You can however download the sitemap of a website and use that as input.

Check Only Specific Files

Section titled “Check Only Specific Files”
Terminal window
lychee README.md
lychee test.html info.txt
lychee test.html info.txt https://example.com

This command checks only the links in the given files. It also demonstrates how to check multiple inputs, such as files and URLs in a single command.

Section titled “Check Links In Directories, But Block All Network Requests”
Terminal window
lychee --offline path/to/directory

This will only check the links in the files in the given directory and not make any network requests. It is helpful for a quick local “linting” of files.

Section titled “Check Links In A Remote File”
Terminal window
lychee https://raw.githubusercontent.com/lycheeverse/lychee/master/README.md

If a URL is given as input and it ends with a file extension other than .html, lychee respects the file extension and interprets the file accordingly. Here, we interpret the file as Markdown.

Section titled “Check links from stdin”
Terminal window
cat test.md | lychee -
echo 'https://example.com' | lychee -

You don’t need to put links into a file first. You can also pipe them into lychee directly.

Section titled “Check Links In Local Files Via Shell Glob”
Terminal window
lychee 'public/**/*.html'

Have many files in the same directory structure you want to check? You don’t need to list them all. Just use a shell glob!

The above command checks all .html files in the public directory and its subdirectories.

Advanced Globbing And ~ Expansion

Section titled “Advanced Globbing And ~ Expansion”
Terminal window
lychee '~/projects/big_project/\*_/README._'

This command checks all README files inside the big_project directory with files ending in any file extension. The ~ gets expanded to your home directory.

Section titled “Ignore Case When Globbing And Check Result For Each Link”
Terminal window
lychee --glob-ignore-case --verbose '~/projects/\*_/[r]eadme._'

In this command, we ignore the case when globbing, so it matches

  • ~/projects/my_project_/readme.md
  • ~/projects/cool_app_/README.txt
  • ~/projects/website_/readme.rst
  • ~/projects/rust_game_/README
  • ~/projects/python_script_/Readme.markdown
Section titled “Check Links From Epub File”

If you have atool installed, you can check links inside .epub files as well!

Terminal window
acat -F zip {file.epub} "_.xhtml" "_.html" | lychee -

GitHub Action

Section titled “GitHub Action”

Lychee is also available as a GitHub Action.