Installation

If you are upgrading from older versions of LinkChecker you should also read the upgrading documentation stored in Upgrading.

When installing from source, for application translations to be installed polib needs to be installed before LinkChecker. After LinkChecker installation polib can be removed.

Installing from the GitHub release assets requires setuptools-scm-git-archive.

pip-run may be useful for both of these cases.

There are several steps to resolve problems with detecting the character encoding of checked HTML pages: first ensure the web server, if used, is not returning an incorrect charset in the Content-Type header; second, if possible add a meta element to the HTML page with the correct charset; finally, check chardet is not installed, Requests >= 2.26 will install charset-normalizer, Beautiful Soup has its own encoding detector but will use in order of preference cchardet, chardet or charset-normalizer (Beautiful Soup >= 4.11). You might find that one of the other three detectors works better for your pages. There may already be a system copy of e.g. chardet installed; installing LinkChecker in a Python venv gives control over which packages are used.

Setup with pip

pip can be used to install LinkChecker on the local system.

If you want application translations, first: pip3 install polib

Then this command will install LinkChecker from the latest source: pip3 install git+https://github.com/linkchecker/linkchecker.git

Setup for Windows

Python from the Microsoft Store does include pip, but installing within Windows Subsystem for Linux (WSL) is the preferred option: https://docs.microsoft.com/en-us/windows/python/beginners

Setup for macOS

Python from Homebrew includes pip. Otherwise python3 -m ensurepip --upgrade can be used to install pip (untested): https://pip.pypa.io/en/stable/installation/

Setup for GNU/Linux

On all major Linux distributions (Debian, Mandriva, Redhat, Suse, Ubuntu), the linkchecker package is available for installation. pip will be available, often as a package e.g. python3-pip, to install the latest LinkChecker.

Manual setup for Unix systems

First, install the required software.

  1. Python >= 3.7 from https://www.python.org/

    Be sure to also have installed the included distutils module. On most distributions, the distutils module is included in an extra python-dev package.

  2. Python Requests package from https://pypi.org/project/requests/

  3. Python Beautiful Soup package from https://pypi.org/project/beautifulsoup4/

  4. Optional, installation time only, for translations: polib Python module from https://pypi.org/project/polib/

  5. Optional, for bash-completion: argcomplete Python module from https://pypi.org/project/argcomplete/

  6. Optional, for displaying country codes: GeoIP from https://pypi.org/project/GeoIP/

  7. Optional, used for Virus checking: ClamAv from https://www.clamav.net/

  8. Optional, to run the WSGI web interface: Apache from https://httpd.apache.org/ mod_wsgi from https://pypi.org/project/mod-wsgi/

Note for developers: if you want to regenerate the po/linkchecker.pot template from the source files, you will need xgettext with Python support. This is available in gettext >= 0.12.

Now install the application.

  1. Compile Python modules

    Run python setup.py sdist --manifest-only to create the MANIFEST file. Run python setup.py build to compile the Python files. For help about the setup.py script options, run python setup.py --help.

    1. Installation as root

      Run sudo python setup.py install to install LinkChecker.

    2. Installation as a normal user

      Run python setup.py install --home $HOME. Note that you have to adjust your PATH and PYTHONPATH environment variables, eg. by adding the commands export PYTHONPATH=$HOME/lib/python and export PATH=$PATH:$HOME/bin to your shell configuration file.

      For more information look at the Modifying Python’s search path documentation.

After installation

LinkChecker is now installed. Have fun!

WSGI web interface

The included WSGI script can run LinkChecker with a nice graphical web interface. You can use and adjust the example HTML files in the lconline directory to run the script.

  1. Note that running LinkChecker requires CPU and memory resources. Allowing a WSGI script to execute such a program for possibly a large number of users might deplete those resources. Be sure to only allow access from trusted sites to this script.

  2. Copy the script lc.wsgi in the WSGI directory.

  3. Adjust the “action=…” parameter in lconline/lc_cgi.html to point to your WSGI script.

  4. If you use Apache, copy config/linkchecker.apache2.conf into your Apache configuration directory (eg. /etc/apache2/conf.d) and enable it.

  5. Load the lconline/index.html file, enter an URL and click on the check button.

  6. If something goes wrong, check the following:

    1. look in the error log of your web server

    2. be sure that you have enabled WSGI support in your web server, for example by installing mod_wsgi for Apache

    3. be sure that you have enabled the negotiation and versioning modules for Apache: a2enmod version a2enmod negotiation