Folder naming convention for python projects

Folder naming convention for python projects

There are three conventions, which you might find confusing.

  1. The standard

PEP8 defines a standard for how to name packages and modules:

Modules should have short, all-lowercase names. Underscores can be used in the module name if it improves readability. Python packages should also have short, all-lowercase names, although the use of underscores is discouraged.

  1. Actually, nobody cares about the recommendation about not using underscores

Even though its in PEP8, many packages use underscores and the community doesnt consider it poor practice. So you see many names like sqlalchemy_searchable, etc.

Although you can create a folder with a name which does not match your package name, its generally a bad idea to do so because it makes things more confusing.

So youll usually use all-lowercase names with underscores for your folders.

  1. Package naming on pypi

The name of a package when its installed doesnt need to match the name its published to on pypi (the source for pip installs). Packages on pypi tend to be named with hyphens, not underscores.
e.g. flask-cors, which installs the package flask_cors.

However, youll note that if you follow-up on this example that flask-corss GitHub repo defines the package code in a flask_cors/ directory. This is the norm.

It gets a bit messy though, because pip package installation is case-insensitive and treats underscores and hyphens equivalently. So Flask-Cors, fLASK_cOrs, etc are all equivalent.
Personally, I dont like playing games with this — I recommend just naming packages on pypi in all-lowercase with hyphens, which is what most people do.

Disclaimer: I dont own or maintain sqlalchemy-searchable or flask-cors, but at time of writing theyre good examples of packages with underscores in their names.

Here is an example of how we might organize a repository called altimeter-valport-lcm which contains the package altimeter_valeport_lcm. The package contains the module altimeter_valeport_lcm.parser:

├── altimeter_valeport_lcm
│   ├──
│   ├──
│   ├──
│   └──
├── README.rst


  • All lowercase for choosing the package name.
  • The repository should use the same name as the package, except that the repository substitutes dashes (-) for underscores (_).

Read More.

Folder naming convention for python projects

Python packages should also have short, all-lowercase names, although the use of underscores is discouraged. Pep 8 Style Guide

This is the recommendation for packages, which is the main folder containing modules, for testing, setup, and script files, *.py and Therefore, I am assuming the folder is the package and as such, should be all lower case with no underscore (see the link Some Package Github ).

Leave a Reply

Your email address will not be published. Required fields are marked *