Set homepage in pyproject.toml

[JakobDev]

Problem description

How can I set a Homepage in a pyproject.toml? The guide shows this:

[project.urls]
"Homepage" = "https://github.com/pypa/sampleproject"
"Bug Tracker" = "https://github.com/pypa/sampleproject/issues"

But this is just recognized as a normal URL field by PyPI and not as the homepage as the url argument from the old setup.py.

[henryiii]

See https://peps.python.org/pep-0621/#have-a-separate-url-home-page-field

It was considered redundant and isn’t included. Some backends try to fill it from the urls if there’s a matching name (setuptools 61+ does, I think). I think others just ignore it entirely as no longer needed.

[mara004]

The thing is, then no homepage is shown by pip:

[project.urls]
homepage = "https://github.com/pypdfium2-team/pypdfium2"  # FIXME not shown by pip
documentation = "https://pypdfium2.readthedocs.io/"
changelog = "https://pypdfium2.readthedocs.io/en/stable/changelog.html"

$ python3 -m pip show pypdfium2
Name: pypdfium2
Version: 4.0.0b1
Summary: Python bindings to PDFium
Home-page: 
Author: pypdfium2-team
Author-email: geisserml <[email protected]>
License: Apache-2.0 or BSD-3-Clause
Location: /home/me/.local/lib/python3.11/site-packages
Editable project location: /home/me/projects/pypdfium2
Requires: 
Required-by: 

[Pablo1990]

Hi,

I have the same problem that you had. For now, I've just created a setup.cfg file with the following fields:

[metadata]
url = URL1
author = Person1
author_email = AuthorEmail

Meanwhile, I have everything else in the pyproject.toml file.

It worked for me! Hope it helps you!
Pablo

[mara004]

Of course you can work around the issue with the old setup files. But that doesn't fix the problem.

I think pip should look for a homepage entry in [project.urls].
See pypa/pip#11138, pypa/pip#11221, #670

[bulletmark]

I started to port one of my projects from setup.py to pyproject.toml but then found this issue which has put me off. Question to the participants here which is not clear from the discussion - the second response from @henryiii implies that if I set a homepage in [project.urls] and I use setuptools >= 61 for the build then I will at least get a homepage link on the PyPI project page (which is important) but just not see a Home-page field in pip show (less important). Is this the case?

If I can't get a PyPi home page link other than by specifying a separate setup.cfg then I won't bother yet.

[GalaxySnail]

IMO the key problem is the relationship between Home-page in the core metadata specification and project.urls.Homepage in pyproject.toml is not clearly specified. Some facts:

1. Home-page: and Project-URL: Homepage, in the core metadata specification are similar in concept.
2. A separate url/home-page field in project table is considered redundant in PEP 621. [1]
3. The Home-page metadata is not deprecated.
4. It is not clearly specified whether project.urls.homepage should be mapped to the Home-page metadata by a build backend.
5. For metadata consumers, the meaning of Home-page: and Project-URL: Homepage is not very clear.
6. PyPI treats Home-page: and Project-URL: Homepage as equivalent. [2] [3]
   (By the way, Download-URL: and Project-URL: Download are also treated as equivalent.)

There are some potential solutions:

1. Specify that build backends should map project.urls.homepage to the Home-page metadata and map project.urls.download to the Download-URL metadata.
2. Specify that metadata consumers should treat Project-URL: Homepage and Project-URL: Download as equivalent to Home-page and Download-URL, and maybe deprecate Home-page and Download-URL since they are not supported by pyproject.toml.

[henryiii]

The biggest issue with Home-page is projects are not consistent as to what a "Homepage" means; does it mean the GitHub page, or the docs page, or something else? pypa/wheel doesn't want to set any URLs to "Homepage" because it's ambiguous. If it had been Docs-page and Source-page or something like that, it likely would be better, but it isn't. Downstream users can't assume what the Home-page (or a Homepage URL) points at. So I'd say the "solution 2" above looks good to me, except downstream users can't really use Home-page as it is anyway, so not sure there's any need to tell them to look for a Homepage URL, or to ask users to provide it. I'm not sure many projects used Download-URL.

AFAIK, the only issue here is pip show, which displays Home-page by default, but not URLs. PyPI nicely displays all your URLs.

[GalaxySnail]

The biggest issue with Home-page is projects are not consistent as to what a "Homepage" means; does it mean the GitHub page, or the docs page, or something else?
Downstream users can't assume what the Home-page (or a Homepage URL) points at.

It doesn't sound like a big problem. "Homepage" seems ambiguous to downstream users, but users hardly care about what "Homepage" exactly means. Users usually want an upstream URL of this library, it can be a source code page, a docs page, or a home page in the narrowest sense (for example, https://cython.org), it's OK. Many Linux package managers have one and only one URL for each package, but I saw few poeple complain about it.

AFAIK, the only issue here is pip show, which displays Home-page by default, but not URLs. PyPI nicely displays all your URLs.

Fair enough. It would be better to show all URLs instead of only one Home-page URL.

[mara004]

It would be better to show all URLs instead of only one Home-page URL.

This is the behavior we get with pip show -v, but it's probably overkill for default pip show.

That said, I agree with @GalaxySnail, nevermind about ambiguity.
My understanding of "Homepage" would be the place where a newcomer should go first. This is up to developers to define. If a project has an own website, it would commonly be that. Otherwise, it could be either repository or docs, depending on how the project is laid out.

[dlenski]

I'm in the same boat as @bulletmark was a year ago:

I started to port one of my projects from setup.py to pyproject.toml but then found this issue which has put me off. Question to the participants here which is not clear from the discussion - the second response from @henryiii implies that if I set a homepage in [project.urls] and I use setuptools >= 61 for the build then I will at least get a homepage link on the PyPI project page (which is important) but just not see a Home-page field in pip show (less important). Is this the case?

If I can't get a PyPi home page link other than by specifying a separate setup.cfg then I won't bother yet.

I've ported a project to pyproject.toml with Poetry. I set description and repository in the [tool.poetry] section (chimping from the fields I see in other projects).

Then I run poetry build and look at the files in dist/:

1. Sdist/source tarball.

   $ tar -Oxf dist/${PROJECT}-${VERSION}.tar.gz ${PROJECT}-${VERSION}/PKG-INFO | head
   Metadata-Version: 2.1
   …
   Summary: <as expected>
   Home-page: <as expected>
   

2. Wheel.

   $ unzip -c -x dist/${PROJECT}-${VERSION}-py3-none-any.whl ${PROJECT}-${VERSION}.dist-info/METADATA | head
   Metadata-Version: 2.1
   …
   Summary: <as expected>
   Home-page: <as expected>
   

However, PyPI isn't showing any Description or Homepage when I upload this package. 😕

I have older projects using setuptools, where Description and Homepage show up just fine on PyPI (example), and so I compared against the source/sdist tarballs built for those packages. I can't find any meaningful difference in the generated PKG-INFO file that would explain this difference.

Can anyone explain what I might be doing wrong here?

[henryiii]

You don't want the Home-page: metadata field. That's finally going to be officially deprecated in PEP 753. What you want is Project-URLs. If you use a name like homepage, those show up correctly, here's a comparison of the link you gave vs. pyproject-metdata, a PEP 621 project:

Your example	A PEP 621 project

I would recommend using a PEP 621 backend instead of Poetry until they support PEP 621. PDM, uv, Hatch all support any build backend that supports PEP 621.

[slonopotamus]

I lost track of this issue a long time ago, but take a look at https://pypi.org/project/ue4-docker/. It uses pyproject.toml and homepage properly shows on PyPI.

[henryiii]

I see a description?

(I could've sworn that I did not see one when I first looked, though)

[dlenski]

I see a description?

(I could've sworn that I did not see one when I first looked, though)

You're right @henryiii. This turned out to be largely a PEBKAC error.

I apparently had figured out how to add the right fields for homepage+description (turns out that either the old/deprecated or new/shiny versions still work), but I had also inadvertently upload a higher-version-number sdist while flailing around and trying different things… so that higher-numbered sdist "shadowed" the default view of the package until I "yanked" it.

Derp derp derp. Sorry to waste others' time on this 🤦🏻.

[slonopotamus]

So... Should this issue be closed given that there is a working way to specify homepage in pyproject.toml using [project.urls] Homepage = "..."?

[henryiii]

PEP 753 was just accepted yesterday, which deprecates Home-page entirely, and recommends build backends stop filling it. So I'd say yes.