LINKCHECKER(1)

📦
version 10.6.0 · 5 versions
, in fedora 44, nixos 26.05, nixpkgs unstable, ubuntu resolute, ubuntu stonking

LINKCHECKER(1) 💅 the LinkChecker manual, bestie edition

okay so. linkchecker is the LinkChecker command line client, and it lives in manual section 1, and it is literally about to change your whole link-checking life. sit down, hydrate, let's go 🫶

✨ NAME ✨

linkchecker — command line client to check HTML documents and websites for broken links

like, it goes and finds the dead links for you so you don't have to click 4000 things at 2am. iconic behavior. 🦋

🌸 SYNOPSIS 🌸

linkchecker [options] [file-or-url]...

that's it. that's the whole vibe. options, then one or more files or URLs, and she goes to work. ✨

👑 DESCRIPTION 👑

okay so here's what LinkChecker actually brings to the function. LinkChecker features:

  • recursive and multithreaded checking 🌈
  • output in colored or normal text, HTML, SQL, CSV, XML or a sitemap graph in different formats 💅
  • support for HTTP/1.1, HTTPS, FTP, mailto: and local file links 🔥
  • restriction of link checking with URL filters 🎀
  • proxy support 🧚
  • username/password authorization for HTTP and FTP 👑
  • support for robots.txt exclusion protocol ⭐
  • support for Cookies 🍓
  • support for HTML5 💜
  • Antivirus check 🦋
  • a command line and web interface 🌸

she does ALL of that. no cap. 😭

💖 EXAMPLES 💖

the most common use checks the given domain recursively:

$ linkchecker http://www.example.com/
⚠️ beware that this checks the whole site which can have thousands of URLs. use the -r option to restrict the recursion depth, bestie, or you will be waiting a while. 😭

don't check URLs with /secret in its name. all other links are checked as usual:

$ linkchecker --ignore-url=/secret mysite.example.com

checking a local HTML file on Unix:

$ linkchecker ../bla.html

checking a local HTML file on Windows:

C:\> linkchecker c:empest.html

you can skip the http:// url part if the domain starts with www.:

$ linkchecker www.example.com

you can skip the ftp:// url part if the domain starts with ftp.:

$ linkchecker -r0 ftp.example.com

generate a sitemap graph and convert it with the graphviz dot utility:

$ linkchecker -odot -v www.example.com | dot -Tps > sitemap.ps

see? ate. 💅

✨ OPTIONS ✨

🌷 General options

  • -f FILENAME, --config=FILENAME — use FILENAME as configuration file. by default LinkChecker uses $XDG_CONFIG_HOME/linkchecker/linkcheckerrc. 👑
  • -h, --help — help me! print usage information for this program. (yes, she's asking for help. relatable.) 🙈
  • -t NUMBER, --threads=NUMBER — generate no more than the given number of threads. default number of threads is 10. to disable threading specify a non-positive number. 🔥
  • -V, --version — print version and exit. 💜
  • --list-plugins — print available check plugins and exit. 🎀

🌈 Output options

🍓 URL checking results

  • -F TYPE[/ENCODING][/FILENAME], --file-output=TYPE[/ENCODING][/FILENAME] — output to a file linkchecker-out.TYPE, $XDG_DATA_HOME/linkchecker/failures for the failures output type, or FILENAME if specified. the ENCODING specifies the output encoding, the default is that of your locale. valid encodings are listed at https://docs.python.org/library/codecs.html#standard-encodings. the FILENAME and ENCODING parts of the none output type will be ignored, else if the file already exists, it will be overwritten. you can specify this option more than once. valid file output TYPEs are text, html, sql, csv, gml, dot, xml, sitemap, none or failures. default is no file output. the various output types are documented below. note that you can suppress all console output with the option -o none. 💅
  • --no-warnings — don't log warnings. default is to log warnings. 🫶
  • -o TYPE[/ENCODING], --output=TYPE[/ENCODING] — specify the console output type as text, html, sql, csv, gml, dot, xml, sitemap, none or failures. default type is text. the various output types are documented below. the ENCODING specifies the output encoding, the default is that of your locale. valid encodings are listed at https://docs.python.org/library/codecs.html#standard-encodings. 🌸
  • -v, --verbose — log all checked URLs, overriding --no-warnings. default is to log only errors and warnings. 🔥

🦋 Progress updates

  • --no-status — do not print URL check status messages. (she goes quiet. mysterious. main character energy.)

⭐ Application

  • -D STRING, --debug=STRING — print debugging output for the given logger. available debug loggers are cmdline, checking, cache, plugin and all. all is an alias for all available loggers. this option can be given multiple times to debug with more than one logger. 🧚

💀 Quiet

  • -q, --quiet — quiet operation, an alias for -o none that also hides application information messages. this is only useful with -F, else no results will be output. fr fr, read that last part again. 😭

👑 Checking options

  • --cookiefile=FILENAME — use initial cookie data read from a file. the cookie data format is explained below. 🍓
  • --check-extern — check external URLs. 🌈
  • --ignore-url=REGEX — URLs matching the given regular expression will only be syntax checked. this option can be given multiple times. see section REGULAR EXPRESSIONS for more info. 🎀
  • --no-follow-url=REGEX — check but do not recurse into URLs matching the given regular expression. this option can be given multiple times. see section REGULAR EXPRESSIONS for more info. 💜
  • --no-robots — check URLs regardless of any robots.txt files. 🫶
  • -p, --password — read a password from console and use it for HTTP and FTP authorization. for FTP the default password is anonymous@. for HTTP there is no default password. see also -u. 🔐
  • -r NUMBER, --recursion-level=NUMBER — check recursively all links up to given depth. a negative depth will enable infinite recursion. default depth is infinite. (infinite!! the way that she just keeps going??) 😭
  • --timeout=NUMBER — set the timeout for connection attempts in seconds. the default timeout is 60 seconds. ⏳
  • -u STRING, --user=STRING — try the given username for HTTP and FTP authorization. for FTP the default username is anonymous. for HTTP there is no default username. see also -p. 👑
  • --user-agent=STRING — specify the User-Agent string to send to the HTTP server, for example "Mozilla/4.0". the default is "LinkChecker/X.Y" where X.Y is the current version of LinkChecker. 🦋

🌸 Input options

  • --stdin — read from stdin a list of white-space separated URLs to check. 💅
  • FILE-OR-URL — the location to start checking with. a file can be a simple list of URLs, one per line, if the first line is "# LinkChecker URL list". 🎀

💜 CONFIGURATION FILES 💜

configuration files can specify all options above. they can also specify some options that cannot be set on the command line. see linkcheckerrc(5) for more info. (yes bestie, there's a whole other manual page for the config file. she's thorough like that.) 🧚

🔥 OUTPUT TYPES 🔥

⚠️ note that by default only errors and warnings are logged. you should use the option --verbose to get the complete URL list, especially when outputting a sitemap graph format. like, especially then. no cap.
  • text — standard text logger, logging URLs in keyword: argument fashion. ✨
  • html — log URLs in keyword: argument fashion, formatted as HTML. additionally has links to the referenced pages. invalid URLs have HTML and CSS syntax check links appended. 🌈
  • csv — log check result in CSV format with one URL per line. 🍓
  • gml — log parent-child relations between linked URLs as a GML sitemap graph. 🦋
  • dot — log parent-child relations between linked URLs as a DOT sitemap graph. 🎀
  • gxml — log check result as a GraphXML sitemap graph. 💜
  • xml — log check result as machine-readable XML. ⭐
  • sitemap — log check result as an XML sitemap whose protocol is documented at https://www.sitemaps.org/protocol.html. 👑
  • sql — log check result as SQL script with INSERT commands. an example script to create the initial SQL table is included as create.sql. 💅
  • failures — suitable for cron jobs. logs the check result into a file $XDG_DATA_HOME/linkchecker/failures which only contains entries with invalid URLs and the number of times they have failed. 🔥
  • none — logs nothing. suitable for debugging or checking the exit code. 💀

🧚 REGULAR EXPRESSIONS 🧚

LinkChecker accepts Python regular expressions. see https://docs.python.org/howto/regex.html for an introduction. an addition is that a leading exclamation mark negates the regular expression. (so ! at the front = "not this one, bestie") 💖

a cookie file contains standard HTTP header (RFC 2616) data with the following possible names:

  • Host (required) — sets the domain the cookies are valid for. 👑
  • Path (optional) — gives the path the cookies are value for; default path is /. 🌸
  • Set-cookie (required) — set cookie name/value. can be given more than once. 🍪

multiple entries are separated by a blank line. the example below will send two cookies to all URLs starting with http://example.com/hello/ and one to all URLs starting with https://example.org/:

Host: example.com
Path: /hello
Set-cookie: ID="smee"
Set-cookie: spam="egg"

Host: example.org
Set-cookie: baggage="elitist"; comment="hologram"

look at her. sending cookies around like it's nothing. slay. 🫶

🌈 PROXY SUPPORT 🌈

to use a proxy on Unix or Windows set the http_proxy or https_proxy environment variables to the proxy URL. the URL should be of the form http://[user:pass@]host[:port]. LinkChecker also detects manual proxy settings of Internet Explorer under Windows systems. on a Mac use the Internet Config to select a proxy. you can also set a comma-separated domain list in the no_proxy environment variable to ignore any proxy settings for these domains. the curl_ca_bundle environment variable can be used to identify an alternative certificate bundle to be used with an HTTPS proxy. 🔐

setting a HTTP proxy on Unix for example looks like this:

$ export http_proxy="http://proxy.example.com:8080"

proxy authentication is also supported:

$ export http_proxy="http://user1:mypass@proxy.example.org:8081"

setting a proxy on the Windows command prompt:

C:\> set http_proxy=http://proxy.example.com:8080

and that's the proxy situation, bestie 💅

✨ PERFORMED CHECKS ✨

Okay bestie, before literally anything else happens, every single URL has to pass a preliminary syntax test 💅. Tiny little quoting oopsies? Those just get a warning, no biggie. But every other kind of invalid syntax?? That's an error, periodt. Once the syntax check is passed, the URL gets queued up for connection checking. And here's the whole menu of connection check types 👇

  • HTTP links (http:, https:) — After connecting to the given HTTP server, the given path or query is requested. All redirections are followed, and if user/password is given it will be used as authorization when necessary. All final HTTP status codes other than 2xx are errors. Also, HTML page contents are checked for recursion. 🔁
  • Local files (file:) — A regular, readable file that can be opened is valid. A readable directory is also valid. All other files, for example device files, unreadable or non-existing files, are errors. HTML or other parseable file contents are checked for recursion. 🗂️
  • Mail links (mailto:) — A mailto: link eventually resolves to a list of email addresses. And the way it works is, if one address fails, the whole list fails 😭. For each mail address we check the following things:
    1. Check the address syntax, both the parts before and after the @ sign.
    2. Look up the MX DNS records. If we found no MX record, print an error.
    3. Check if one of the mail hosts accept an SMTP connection. Check hosts with higher priority first. If no host accepts SMTP, we print a warning.
    4. Try to verify the address with the VRFY command. If we got an answer, print the verified address as an info.
  • FTP links (ftp:) — For FTP links we do:
    1. connect to the specified host
    2. try to login with the given user and password. The default user is anonymous, the default password is anonymous@.
    3. try to change to the given directory
    4. list the file with the NLST command
  • Unsupported links (javascript:, etc.) — An unsupported link will only print a warning. No further checking will be made, we're not even gonna try 💀.

The complete list of recognized, but unsupported links can be found in the linkcheck/checker/unknownurl.py source file. The most prominent of them should be JavaScript links.

🗺️ SITEMAPS 🗺️

Sitemaps are parsed for links to check, and they can be detected in two ways: either from a sitemap entry in a robots.txt, or when passed as a FILE-OR-URL argument — and in that second case, detection requires the urlset/sitemapindex tag to be within the first 70 characters of the sitemap. Also, heads up: compressed sitemap files are not supported. 🙈

🧩 PLUGINS 🧩

There are two plugin types: connection and content plugins. Connection plugins are run after a successful connection to the URL host. Content plugins are run if the URL type has content (mailto: URLs have no content for example) and if the check is not forbidden (ie. by HTTP robots.txt).

Use the option --list-plugins for a list of plugins and their documentation. All plugins are enabled via the linkcheckerrc(5) configuration file. ✨

🔁 RECURSION 🔁

Before descending recursively into a URL, it has to fulfill several conditions. They are checked in this order, no skipping the line bestie:

  1. A URL must be valid.
  2. A URL must be parseable. This currently includes HTML files, Opera bookmarks files, and directories. If a file type cannot be determined (for example it does not have a common HTML file extension, and the content does not look like HTML), it is assumed to be non-parseable.
  3. The URL content must be retrievable. This is usually the case except for example mailto: or unknown URL types.
  4. The maximum recursion level must not be exceeded. It is configured with the --recursion-level option and is unlimited per default.
  5. It must not match the ignored URL list. This is controlled with the --ignore-url option.
  6. The Robots Exclusion Protocol must allow links in the URL to be followed recursively. This is checked by searching for a "nofollow" directive in the HTML header data.
Note that the directory recursion reads all files in that directory, not just a subset like index.htm. Like, all of them. Every single one. 🫶

📝 NOTES 📝

URLs on the commandline starting with ftp. are treated like ftp://ftp., and URLs starting with www. are treated like http://www.. You can also give local files as arguments. If you have your system configured to automatically establish a connection to the internet (e.g. with diald), it will connect when checking links not pointing to your local host. Use the --ignore-url option to prevent this. 🛑

Javascript links are not supported.

If your platform does not support threading, LinkChecker disables it automatically.

You can supply multiple user/password pairs in a configuration file.

🌍 ENVIRONMENT 🌍

  • http_proxy — specifies default HTTP proxy server
  • https_proxy — specifies default HTTPS proxy server
  • curl_ca_bundle — an alternative certificate bundle to be used with an HTTPS proxy
  • no_proxy — comma-separated list of domains to not contact over a proxy server
  • LC_MESSAGES, LANG, LANGUAGE — specify output language

🚦 RETURN VALUE 🚦

The return value is 2 when

  • a program error occurred.

The return value is 1 when

  • invalid links were found or
  • link warnings were found and warnings are enabled

Else the return value is zero. Clean run, iconic behaviour 💅

😭 LIMITATIONS 😭

LinkChecker consumes memory for each queued URL to check. With thousands of queued URLs the amount of consumed memory can become quite large. This might slow down the program or even the whole system. So like, be mindful bestie, don't queue a million URLs and then blame the tool 🫠

📂 FILES 📂

  • $XDG_CONFIG_HOME/linkchecker/linkcheckerrc — default configuration file
  • $XDG_DATA_HOME/linkchecker/failures — default failures logger output filename
  • linkchecker-out.TYPE — default logger file output name

👀 SEE ALSO 👀

👑 AUTHOR 👑

Bastian Kleineidam <bastian.kleineidam@web.de>

2000-2016 Bastian Kleineidam, 2010-2025 LinkChecker Authors

And that's a wrap on the whole page, bestie! This lil manual is for version 10.5.0.post14+g8c3a6f77, dated July 28, 2025 — go forth and check those links, you absolute main character 🦋✨ LINKCHECKER(1) forever 💅

📦 where this page comes from