Python package name conventions


Is there a package naming convention for Python like Java’s Most of the time I see simple, potentially colliding package names like “web“.

If there is no such convention, is there a reason for it? What do you think of using the Java naming convention in the Python world?

Asked By: deamon



I’ve been using python for years and 99.9% of the collisions I have seen comer from new developers trying to name a file “”. I can see some advantages to the Java scheme, but most developers are smart enough to pick reasonable package names, so it really is’t that big of a problem.

Answered By: mikerobi

The reason there’s normally no package hierarchy is because Python packages aren’t easily extended that way. Packages are actual directories, and though you can make packages look in multiple directories for sub-modules (by adding directories to the __path__ list of the package) it’s not convenient, and easily done wrong. As for why Python packages aren’t easily extended that way, well, that’s a design choice. Guido didn’t like deep hierarchies (and still doesn’t) and doesn’t think they’re necessary.

The convention is to pick a toplevel package name that’s obvious but unique to your project — for example, the name of the project itself. You can structure everything inside it however you want (because you are in control of it.) Splitting the package into separate bits with separate owners is a little more work, but with a few guidelines it’s possible. It’s rarely needed.

Answered By: Thomas Wouters

The Java’s conventions also has its own drawbacks. Not every opensource package has a stable website behind it. What should a maintainer do if his website changes? Also, using this scheme package names become long and hard to remember. Finally, the name of the package should represent the purpose of the package, not its owner

Answered By: user283145

There is no Java-like naming convention for Python packages. You can of course adopt one for any package you develop yourself, but you might have to invasively edit any package you may adopt from third parties, and the “culturally alien” naming convention will probably sap the changes of your own packages to be widely adopted outside of your organization.

Technically, there would be nothing wrong with Java’s convention in Python (it would just make some from statements a tad longer, no big deal), but in practice the cultural aspects make it pretty much unfeasible.

Answered By: Alex Martelli

Python has two “mantras” that cover this topic:

Explicit is better than implicit.


Namespaces are one honking great idea — let’s do more of those!

There is a convention for naming of and importing of modules that can be found in The Python Style Guide (PEP 8).

The biggest reason that there is no such convention to consistently prefix your modules names in a Java style, is because over time you end up with a lot of repetition in your code that doesn’t really need to be there.

One of the problems with Java is it forces you to repeat yourself, constantly. There’s a lot of boilerplate that goes into Java code that just isn’t necessary in Python. (Getters/setters being a prime example of that.)

Namespaces aren’t so much of a problem in Python because you are able to give modules an alias upon import. Such as:

import as shortername

So you’re not only able to create or manipulate the namespace within your programs, but are able to create your own keystroke-saving aliases as well.

Answered By: jathanism

There’s nothing stopping you using that convention if you want to, but it’s not at all standard in the Python world and you’d probably get funny looks. It’s not much fun to take care of admin on packages when they’re deeply nested in com.

It may sound sloppy to someone coming from Java, but in reality it doesn’t really seem to have caused any big difficulties, even with packages as poorly-named as

The place where you often do get namespace conflicts in practice is relative imports: where code in package.module1 tries to import module2 and there’s both a package.module2 and a module2 in the standard library (which there commonly is as the stdlib is large and growing). Luckily, ambiguous relative imports are going away.

Answered By: bobince

An update for anyone else who comes looking for this:

As of 2012, PEP 423 addresses this. PEP 8 touches on the topic briefly, but only to say: all lowercase or underscores.

The gist of it: pick memorable, meaningful names that aren’t already used on PyPI.

Answered By: Tom