In a correct src-layout project, the only things that should be present in the src directory are the top-level import packages and top-level import modules (sub-packages are in the sub-directories of the top-level packages, obviously).

By convention each distribution package contains one and only one top-level import package (or top-level import module). And I guess that this convention is the "de facto standard" that is asked for in the question.

In the case of the example shown in the question, if the project had both src/mypkg and src/mypkg2 directories, then the project would have 2 top-level import packages, which is unconventional (but possible).

Famous example of project not following this convention is setuptools, it has 2 top-level imports: setuptools and pkg_resources.

I do not know of any authoritative documentation that clarifies this specific point of the src-layout, the closest I can find is "src layout vs flat layout" on the Python Packaging User Guide.

Answer from sinoroc on Stack Overflow
🌐
Python Packaging
packaging.python.org β€Ί en β€Ί latest β€Ί discussions β€Ί src-layout-vs-flat-layout
src layout vs flat layout - Python Packaging User Guide
The β€œflat layout” refers to organising a project’s files in a folder or repository, such that the various configuration files and import packages are all in the top-level directory. . β”œβ”€β”€ README.md β”œβ”€β”€ noxfile.py β”œβ”€β”€ pyproject.toml β”œβ”€β”€ setup.py β”œβ”€β”€ awesome_package/ β”‚ β”œβ”€β”€ __init__.py β”‚ └── module.py └── tools/ β”œβ”€β”€ generate_awesomeness.py └── decrease_world_suck.py Β· The β€œsrc layout” deviates from the flat layout by moving the code that is intended to be importable (i.e.
🌐
Reddit
reddit.com β€Ί r/learnpython β€Ί using a src directory for a python package
r/learnpython on Reddit: Using a src directory for a Python package
August 16, 2022 - According to the Python Packaging User Guide, a src directory should contain a sub-directory which contains the files for a Python package (see example below). packaging_tutorial/ β”œβ”€β”€ LICENSE β”œβ”€β”€ pyproject.toml β”œβ”€β”€ README.md β”œβ”€β”€ src/ β”‚ └── example_package_YOUR_USERNAME_HERE/ β”‚ β”œβ”€β”€ __init__.py β”‚ └── example.py └── tests/ It seems unnecessary to store all the package files within a sub-folder of the src directory.
🌐
pyOpenSci
pyopensci.org β€Ί python-package-guide β€Ί package-structure-code β€Ί python-package-structure.html
Python Package Structure & Layout β€” Python Packaging Guide
tests/ This directory contains the tests for your project code. In a src/ layout, tests are normally included at the same directory level as the src/ folder. src/package/: this is the directory that contains the code for your Python project.
🌐
Medium
medium.com β€Ί @adityaghadge99 β€Ί python-project-structure-why-the-src-layout-beats-flat-folders-and-how-to-use-my-free-template-808844d16f35
Python Project Structure: Why the β€˜src’ Layout Beats Flat Folders (and How to Use My Free Template) | by Aditya Ghadge | Medium
May 17, 2025 - You’ll see big libraries like Pandas, FastAPI, and even parts of PyTorch living inside a src/ folder. Here’s why that one little directory saves so many headaches. Python’s import rules always scan your current working directory first. If your development copy (/home/user/project/) has the same package name as the one you pip-installed, Python might grab the wrong oneβ€”and silent bugs follow.
🌐
B-List
b-list.org β€Ί weblog β€Ί 2023 β€Ί dec β€Ί 15 β€Ί python-packaging-src-layout
Python packaging: use the "src" - James Bennett
December 15, 2023 - One is to begin running your tests, at least in CI, with the -I flag to the Python interpreter (i.e., instead of running pytest, run python -Im pytest). This puts the interpreter into β€œisolated mode” where, among other things, the current directory is not on the import path. This is a good idea for almost any command you’ll run in CI, because isolated mode can cut off a lot of easy attack vectors. The other thing is… stop putting your module at the top level. Instead, adopt the src/ layout or a variation of it, where your module is inside a directory called src/. This way, even locally and even when you forget to use -I, running tests will require that the package successfully build and install, because the module will no longer be top-level and thus no longer implicitly on the import path.
Find elsewhere
🌐
Real Python
realpython.com β€Ί ref β€Ί best-practices β€Ί project-layout
project layout | Python Best Practices – Real Python
Choose wisely between a src/ or flat layout: For packages intended to be installed, published, or reused, consider the src/ layout, which separates source code from other components and prevents issues with imports.
Top answer
1 of 1
20

There is an interesting blog post about this topic; basically, using src prevents that when running tests from within the project directory, the package source folder gets imported instead of the installed package (and tests should always run against installed packages, so that the situation is the same as for a user).

Consider the following example project where the name of the package under development is mypkg. It contains an __init__.py file and another DATA.txt non-code resource:

.
β”œβ”€β”€ mypkg
β”‚   β”œβ”€β”€ DATA.txt
β”‚   └── __init__.py
β”œβ”€β”€ pyproject.toml
β”œβ”€β”€ setup.cfg
└── test
    └── test_data.py

Here, mypkg/__init__.py accesses the DATA.txt resource and loads its content:

from importlib.resources import read_text
  
data = read_text('mypkg', 'DATA.txt').strip()  # The content is 'foo'.

The script test/test_data.py checks that mypkg.data actually contains 'foo':

import mypkg
  
def test():
    assert mypkg.data == 'foo'

Now, running coverage run -m pytest from within the base directory gives the impression that everything is alright with the project:

$ coverage run -m pytest
[...]
test/test_data.py .                                             [100%]

========================== 1 passed in 0.01s ==========================

However, there's a subtle issue. Running coverage run -m pytest invokes pytest via python -m pytest, i.e. using the -m switch. This has a "side effect", as mentioned in the docs:

[...] As with the -c option, the current directory will be added to the start of sys.path. [...]

This means that when importing mypkg in test/test_data.py, it didn't import the installed version but it imported the package from the source tree in mypkg instead.

Now, let's further assume that we forgot to include the DATA.txt resource in our project specification (after all, there is no MANIFEST.in). So this file is actually not included in the installed version of mypkg (installation e.g. via python -m pip install .). This is revealed by running pytest directly:

$ pytest
[...]
======================= short test summary info =======================
ERROR test/test_data.py - FileNotFoundError: [Errno 2] No such file ...
!!!!!!!!!!!!!!! Interrupted: 1 error during collection !!!!!!!!!!!!!!!!
========================== 1 error in 0.13s ===========================

Hence, when using coverage the test passed despite the installation of mypkg being broken. The test didn't capture this as it was run against the source tree rather than the installed version. If we had used a src directory to contain the mypkg package, then adding the current working directory via -m would have caused no problems, as there is no package mypkg in the current working directory anymore.

But in the end, using src is not a requirement but more of a convention/best practice. For example requests doesn't use src and they still manage to be a popular and successful project.

🌐
Informed
informediq.com β€Ί home β€Ί blog β€Ί python src layout for aws lambdas
Python src Layout for AWS Lambdas | Informed
September 7, 2023 - Over the last several years, the Python community has been moving towards a packaging layout format known as the src layout as the recommended way to organize directories and files for Python Packages. ... The src folder only has sub folder[s]. Each sub folder
🌐
Sarah Glasmacher
sarahglasmacher.com β€Ί adding-src-folder-to-ml-project-step-by-step-guide
Adding a src/ Folder to an Existing ML Project: Step-by-Step Guide
April 20, 2025 - # 1. Create folder structure mkdir -p src/smartmeter_forecasting mkdir -p scripts mkdir -p notebooks # 2. Add __init__.py to mark your package touch src/smartmeter_forecasting/__init__.py # 3. Move and rename your existing files mv data_preprocessing.py src/smartmeter_forecasting/preprocessing.py mv explore_smartmeter_data.py notebooks/ # 4. (Optional) Create new placeholders files, e.g. touch src/smartmeter_forecasting/modeling.py ... Caution! Make sure to include the __init__.py file in the main folder of your package (and every sub-package if you create those), as this tells Python that this is indeed a code package.
🌐
GitHub
github.com β€Ί pypa β€Ί packaging.python.org β€Ί issues β€Ί 320
Stance (or discussion) on src/ directory #320
June 7, 2017 - Is there an official stance on the "src/" directory thing? I'm all for it (and @hynek seems to agree) but I haven't found any discussion or explanation about it from the PyPA. The guide doesn't mention it and the sample project doesn't use it.
🌐
Py-pkgs
py-pkgs.org β€Ί 04-package-structure.html
4. Package structure and distribution β€” Python Packages
This is because in most cases the first place Python searches when running import is the current directory (check this by importing sys and running sys.path[0]). Without a β€œsrc” folder, Python will find your package as it exists in the current directory and import it, rather than using it as it would be installed on a user’s machine.
🌐
Xebia
xebia.com β€Ί home β€Ί blog β€Ί setting python source folders in visual studio code
Setting Python Source Folders In Visual Studio Code | Xebia
June 24, 2026 - You set a Python source folder in Visual Studio Code by configuring the PYTHONPATH environment variable. This is done in both the .env file and the settings.json file so that the editor and integrated terminal can recognize the source directory ...
🌐
YouTube
youtube.com β€Ί watch
Adding a SRC Directory: Part #21 Python API Course - YouTube
Enjoy this completely free 19 hour course on developing an API in python using FastAPI. We will build a an api for a social media type app as well as learn t...
Published: May 2, 2022
🌐
Medium
medium.com β€Ί @makcedward β€Ί src-folder-includes-python-files-e-g-91e91c51934b
β€œsrc” folder includes python files (e.g. | by Edward Ma | Medium
January 18, 2021 - β€œsrc” folder includes python files (e.g. *.py) and it should be used in production. All preprocessing logic, prediction logic should be store in here. β€œnotebook” files which is created during …
🌐
Reddit
reddit.com β€Ί r β€Ί learnpython β€Ί comments β€Ί wpkr4q β€Ί using_a_src_directory_for_a_python_package_w
r/learnpython - Using a src directory for a Python package
According to the Python Packaging ... for a Python package (see example below). packaging_tutorial/ β”œβ”€β”€ LICENSE β”œβ”€β”€ pyproject.toml β”œβ”€β”€ README.md β”œβ”€β”€ src/ β”‚ └── example_package_YOUR_USERNAME_HERE/ β”‚ β”œβ”€β”€ __init__.py β”‚ └── example.py └── tests/ It seems unnecessary to store all the package files within a sub-folder of the src ...
🌐
GitHub
github.com β€Ί pypa β€Ί hatch β€Ί discussions β€Ί 1051
"src" layout result in a package named "src" Β· pypa/hatch Β· Discussion #1051
"following" might help? There is always a sub-folder (representing the "Python Import Package") in a "src" folder. The src-folder never contain a py file or something else then another folder.
Author: pypa
🌐
Medium
medium.com β€Ί mlearning-ai β€Ί a-practical-guide-to-python-project-structure-and-packaging-90c7f7a04f95
Guide to Python Project Structure and Packaging | by Joshua Phuong Le | Python in Plain English
June 19, 2024 - There are two main general structures: the flat layout vs the src layout as clearly explained in the official Python packaging guide here. The β€œflat layout” refers to organising a project’s files in a folder or repository, such that the various configuration files and import packages are all in the top-level directory.
🌐
/dev/jcheng
jcheng.org β€Ί post β€Ί python-and-the-src-vs-flat-layout-debate
Python And The 'src-vs-flat' Layout Debate | /dev/jcheng
March 13, 2025 - I used to scoff when I saw Python projects that put their packages into a separate src directory…. To my surprise, cryptography – one of Python’s most modern projects – adopted a src directory … a significant number of projects moved to src since this article has been published…