Valid modules names

There are some restrictions on the names of Python modules because we must be able to import them from Python code and use/reference them with a regular variable. As a result, a valid module name has a lot in common with regular variable names.

A module name:

• Is a string of letters and digits
• Can contain underscores if it helps with readability
• Cannot start with a digit
• Does not contain spaces or other whitespace characters
• Cannot contain any of the following additional characters: \ / : * ? ” < > | –

In addition to these rules, there are some best practices to follow when naming modules. Notable:

• Use lowercase letters for the module name.
• Make sure names are short and descriptive.

Common mistakes

There are some common mistakes that might cause weird issues that are hard to debug, so I want to warn you about them here.

One common mistake is to use reserved words or existing module names for your module. I’ve done so myself, e.g., by creating a module called http while Python already has a module with this name.

Another cause of hard-to-debug errors is naming your module the same as a directory that is present at the same level as the file. E.g., when you create a module customers.py while there’s also a directory customers, you’re going to get in trouble.