What's the difference between --find-links and --index-url pip flags?

Question

Reading the pip documentation, it is not clear to me what is the difference between specifying a --find-links URL or an --index-url/--extra-index-url for extra packages.

The documentation states:

-i, --index-url <url> 

Base URL of Python Package Index (default https://pypi.python.org/simple). This should point to a repository compliant with PEP 503 (the simple repository API) or a local directory laid out in the same format.

-f, --find-links <url> 

If a url or path to an html file, then parse for links to archives. If a local path or file:// url that's a directory, then look for archives in the directory listing.

As far as I understand, there is no real difference between the two, apart from the fact that index URLs must follow PEP 503. I guess the usual logic of choosing the latest version among all the available ones is followed.

Are there any other conceptual differences between the two that I missed? If so, which ones? If not, why having both?

Answer 1

index-url can be considered a page with nothing but packages on it. You're telling pip to find what you want to install on that page; and that page is in a predictable format as per PEP 503. The index will only list packages it has available.

find-links is an array of locations to look for certain packages. You can pass it file paths, individual URLs to TAR or WHEEL files, HTML files, git repositories and more.

You can combine the two, for example, if you wanted to use some packages from your local system and others from a repository online.

You can see all the different ways pip will parse "links to packages" in the pip/test_index.pyp unit tests.