When you manage notes in Obsidian, renaming or deleting notes can leave broken links behind. In this post, I’ll show you how to detect them automatically using lychee, a fast link checker written in Rust.

What is lychee?

lychee is a fast link checker written in Rust.

Highlights:

• Fast checks thanks to async processing
• Native support for Markdown files
• The --offline option lets you check only local links
• Easy to plug into GitHub Actions

Prerequisite: Obsidian link formats

There’s an important caveat to be aware of with lychee. Obsidian’s default wiki-link format [[note]] is not supported. To check links with lychee, you need to use standard Markdown link syntax.

If you set Obsidian’s “New link format” option to “Relative path”, new links will be created in the standard format automatically.

To convert existing wiki links, plugins like obsidian-link-converter come in handy.

Installation

macOS (Homebrew)

brew install lychee

Linux

curl -sSfL https://github.com/lycheeverse/lychee/releases/latest/download/lychee-x86_64-unknown-linux-gnu.tar.gz | tar xzf - -C /usr/local/bin

Basic usage

To check the internal links in an Obsidian vault, use the --offline option:

lychee --offline vault/

Sample output

When broken links exist, you’ll see output like this:

When all links are healthy:

How to write standard Markdown links

Using relative paths lets lychee detect broken links accurately.

[関連ノート](../03_PermanentNotes/related-note.md)
![画像](../97_Assets/image.png)

Tips:

• Use relative paths (../folder/file.md)
• Avoid URL encoding (%20, etc.)

Excluding files

In practice, there will always be files or directories you want to exclude from the check.

Excluding from the command line

# Exclude a specific path
lychee --offline --exclude-path "vault/99_Archive" vault/

# Exclude multiple paths
lychee --offline \
  --exclude-path "vault/99_Archive" \
  --exclude-path "vault/.obsidian" \
  vault/

Excluding via .lycheeignore

You can create a .lycheeignore file at the project root and list exclusion patterns there:

# Exclude archive
vault/99_Archive/

# Exclude templates
vault/98_Templates/

# Exclude files matching a pattern
**/draft-*.md

Managing settings with lychee.toml

Keeping your settings in a config file is convenient:

exclude_path = [
  "vault/99_Archive",
  "vault/.obsidian"
]

# Timeout (for external URL checks)
timeout = 10

# Concurrency
max_concurrency = 32

You can point to the config file when running the command.

lychee --offline --config lychee.toml vault/

Auto-check with a pre-commit hook

To run a link check automatically on commit, set up pre-commit.

.pre-commit-config.YAML

repos:
  - repo: local
    hooks:
      - id: lychee-link-checker
        name: Check links with lychee
        entry: lychee --offline --config lychee.toml vault/
        language: system
        files: '\.md'
        pass_filenames: false

Installing and enabling pre-commit

pip install pre-commit
pre-commit install

Now the link check runs automatically on every commit, and the commit will be aborted if any broken links are found.

Continuous checking with GitHub Actions

Running the link check in CI catches problems before a PR is merged.

.GitHub/workflows/ci.yml

name: CI

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  link-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install lychee
        run: |
          curl -sSfL https://GitHub.com/lycheeverse/lychee/releases/latest/download/lychee-x86_64-unknown-linux-gnu.tar.gz | tar xzf - -C /usr/local/bin

      - name: Run link checker
        run: lychee --offline --config lychee.toml vault/

Running from a Makefile

It’s handy to wrap commands you use often in a Makefile:

VAULT_PATH := vault

.PHONY: check-links
check-links:  ## Check for broken links using lychee
 lychee --offline --config lychee.toml $(VAULT_PATH)/

make check-links

Wrapping up

With lychee, you can check an Obsidian vault for broken links quickly and automatically.

One thing to keep in mind: lychee only supports standard Markdown links. If you’re using wiki links [[note]], you’ll need to convert them to the standard format first.

Keep your knowledge base healthy and free of broken links.

References

• lychee - GitHub
• lychee Documentation
• pre-commit
• obsidian-link-converter