LinkChecker

Common errors

• linkchecker: command not found

  cause The `linkchecker` executable is not in your system's PATH, or the installation via pip/pipx was not properly completed/sourced.
  fix Ensure your shell's PATH includes the directory where pip/pipx installs executables. If using `pipx`, verify `pipx ensurepath` has been run. You can also try running `python -m linkchecker --help`.

• Error: problems with a configuration file or cookie file detected on startup

  cause Since v10.4.0, LinkChecker will explicitly exit if it encounters issues parsing the configuration file (`~/.linkchecker/linkcheckerrc`) or a specified cookie file. Older versions might have raised an exception instead.
  fix Review your configuration file and any cookie files for syntax errors or malformed content. Ensure they are valid and readable.

• TypeError: 'NoneType' object is not iterable (or similar FTP related errors)

  cause Prior to version 10.3.0, the FTP checker module had bugs, including raising `TypeError` and ignoring `maxfilesizedownload`.
  fix Upgrade LinkChecker to version 10.3.0 or later to resolve known issues with FTP link checking.

• linkchecker: error: argument -p/--password: ignored

  cause In versions prior to 10.3.0, the `-p`/`--password` command-line option for specifying passwords was ignored.
  fix Upgrade to LinkChecker 10.3.0 or later. If using configuration files for credentials, verify the format as login entries may have changed (v10.0.0).

Warnings

• breaking LinkChecker transitioned from Python 2 to Python 3 with version 10.0.0. Older versions (pre-10.0.0) are incompatible with Python 3 environments.
  Fix: Ensure you are running Python 3.9+ and install LinkChecker version 10.0.0 or later.
• breaking The minimum required Python version has progressively increased. LinkChecker 10.4.0 and later requires Python 3.9+. Earlier versions had lower requirements (e.g., 3.7 for v10.2.0, 3.8 for v10.3.0).
  Fix: Upgrade your Python environment to 3.9 or newer before installing LinkChecker.
• deprecated Support for checking NNTP and Telnet links was removed in version 10.3.0.
  Fix: If you rely on NNTP or Telnet link checking, you will need to use an older version of LinkChecker or find an alternative solution for these protocols.
• gotcha Prior to version 10.6.0, LinkChecker did not verify the SSL/TLS certificate of the HTTPS connection when an HTTP URL redirected to HTTPS. This could lead to security vulnerabilities.
  Fix: Upgrade to LinkChecker 10.6.0 or later to ensure proper HTTPS certificate verification for redirected links.
• gotcha LinkChecker often reports HTTP 301 (Moved Permanently) redirects as warnings by default, which can result in verbose output.
  Fix: To suppress these warnings, use the `--ignore-warnings=http-redirected` command-line option or configure `ignorewarningsforurls` in your `.linkcheckerrc` configuration file (available since v10.5.0).
• gotcha When checking slow or under-development sites, LinkChecker may report many timeouts.
  Fix: Increase the default timeout duration using the `--timeout=SECONDS` command-line option (e.g., `--timeout=300` for 5 minutes).

Install

• pip install linkchecker Install with pip
• pipx install linkchecker Install with pipx (recommended for CLI tools)

Imports

• linkchecker
  wrong:

  import linkchecker

  correct:

  This is primarily a command-line tool. Direct programmatic import of the main 'linkchecker' utility is not the standard usage pattern. Instead, execute it as a shell command.

  The 'linkchecker' package itself is typically used as a standalone command-line executable, not as a Python library for direct function calls. Trying to `import linkchecker` will likely result in a `ModuleNotFoundError` or expose an internal API not intended for public use.

Quickstart

To check a website for broken links, execute the `linkchecker` command followed by the URL in your terminal. This command will recursively validate pages starting from the given URL and check external links without recursing into them.

linkchecker https://www.example.com