Why are some Python package names different than their import name?

Question

Some packages are imported with a string which is different from the name of the package on PyPI, e.g.:

$ pip list | grep -i "yaml\|qt"  
PyYAML      3.13               
QtPy        1.5.2

• pyyaml (pip instal pyyaml), but import yaml
• qtpy (pip install qtpy), yes import is qtpy but package is QtPy

Several tools can't not handle that, e.g sphinx:

$ make html
WARNING: autodoc: failed to import module 'wireshark' from module 'logcollector.plugins'; the following exception was raised:
No module named 'qtpy'

I don't remember it right now, but same is for tools which scan the requirements.txt file and print warnings that the yaml package isn't installed (but it is and its name is pyyaml).

Answer 1

Because these two concepts are not really related.
One is a python concept of package/module names, the other one a package manager concept.

Look at a simple packaging command with zip:

zip -r MyCoolTool.zip tool.py

The Tool is named tool, which probably is not unique and if you do not know that its MyCoolTool you do not know which tool it is. When I upload it somewhere I name it MyCoolTool, so you now a more unique name, that may be a bit more descriptive.

The other point is, that a pip package may include more modules than just one. PyYAML could for example include a second python module yaml2xml in addtion to yaml.

Finally there can be several implementations. PyYAML sounds like a pure python implementation. Now assume you need a really fast parser, then you may program CYAML with a C-backend, but the same interface at the name yaml.

Answer 2

There are multiple reasons why authors choose to use different names in different environments:

• Drop-in replacements: Sometimes it is helpful when you can install a fork and keep the rest of your code the same. I guess the most famous example is pyyaml / yaml. I did it when I created propy3 which can be used as a drop-in replacement for propy. I would say that this is also what happened with pillow.
• Convenience: beautifulsoup4 can be imported as bs4 (+ package parking for bs4)
• Lost credentials: I don't know of an example where the import name was changed as well, but I think for flask-restx the package name and the import name were changed.

A word of caution

As Ziyad Edher has pointed out in a related discussion, typosquatting is an issue on PyPI (source). If you add packages with different names, this gets more likely.

Other examples

Name in the docs vs "import" package name vs pypi package name vs anaconda packages vs Debian:

• scikit-learn vs sklearn vs scikit-learn vs scikit-learn vs python-sklearn and python3-sklearn
• OpenCV-Pyton vs cv2 vs opencv-python vs py-opencv vs python-opencv
• PyTables vs tables vs tables vs pytables vs python-tables

Answer 3

In case of sphinx you can mock 3rd party packages with: autodoc_mock_imports