Are there any naming conventions for package names?

For the longest time, I’ve had trouble deciding how to write package names when creating a new package (via, or when referencing an existing package in my requirements (via requirements.txt/pyproject.toml).

Should the names use dashes (my-package) or underscores (my_package)?
I know that tools like pip will be able to handle both without any conflicts, but is there any sort of preference?

Part of me tells me to use dashes, since whenever I look at package names in pypi their names seem to be normalized using dashes.
However, if I used underscores, they will allign perfectly with the name I’ll use when importing the package (“pip install typing_extensions” → “import typing_extensions”).

If there is an existing convention, could you please refer me to it?
Thanks in advanced :smile:


My preference is to use names that match normalization rules, i.e. dashes. Then you avoid the confusion when you type pip install foo_bar but get foo-bar instead.

Though I am biased because per Gentoo policy dashes are strongly preferred to underscores, so if you use underscores (or dots, which aren’t allowed in Gentoo at all), I have to end up using different downstream and upstream package name.


I, on the other hand, always use underscore so that the name is the same regardless of whether it’s in metadata, directory listings, import statements, requirements files or wherever. No need for grep 'my[-_]package' or whatever depending on context.

On the other hand, just to note the difference does allow for grep and other automated searches to differentiate references to the import package from that of the distribution package, which is important for many purposes.