Skip to main content

Package a subfolder as a python distribution

Project description

Package a subfolder as a python distribution

  • Free software: Apache Software License 2.0


pip install setuptools-build-subpackage

You can also install the in-development version with:

pip install


This distribution contains a subclass of setuptools’s Distribution, designed to build a “sub-module” as a stand alone distribution.

It is designed to be used with setuptools’s declrative config – i.e. where everything is defined in setup.cfg, not in

For example, take the following layout:

├── example
│   ├──
│   ├── sub_module_a
│   │   ├──
│   │   ├── setup.cfg
│   │   └──
│   └── sub_module_b
│       ├──
│       ├── setup.cfg
│       └──
└── setup.cfg

This assumes we want example.sub_module_a and example.sub_module_b not included in the main distribution, but instead released as separate dists to PyPI.

This set of classes ensures the following:

  • That the top level setup.cfg is not loaded, instead only the one specified from the sub-package

  • That the build/ folder for each sub-package is kept clean, so files from one build don’t leak in to another

  • That the setup.cfg from the sub-folder is present in the built sdist at the top level, meaning it can be installed normally.

  • That a stub file is included for compatibility with older installers

Configure your main dist

First you should exclude the sub-packages from being included in your main dist:



exclude =

Create a setup.cfg for your sub-dist

The requirements and information for the subdist are all driven off a setup.cfg – right now a is not supported. (The included in the sdist will always be generated. PRs welcome if you need something else here.)

See example/sub_module_a/setup.cfg in the source code for a minimal example.

All file paths and module names are absolute, not relative to the location of the setup.cfg file

Build the sdist/bdist

Run the following command:

python -m setuptools_build_subpackage \
  --subpackage-folder example/sub_module_b \
  sdist \

This will create a and .whl file in dist

Including a license comment

If you need a license comment in the generated, pass the --license-template option to sdist

python -m setuptools_build_subpackage \
  --subpackage-folder example/sub_module_b \
  sdist --license-template ./LICENSE \

This argument should be a path to a plain-text license file, that will be included at the top of the generated file, each line prefixed with a python comment.


To run all the tests run:

pip install -e '.[devel]' && pytest

It is also recommended that you install pre-commit to check style rules


1.0.0 (2021-04-23)

  • First release on PyPI.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

setuptools-build-subpackage-1.0.0.tar.gz (14.3 kB view hashes)

Uploaded source

Built Distribution

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page