Install & Compatibility
Where this runs
tested against v0.11.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.000s · 18MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 1.5s · import 0.000s · 19MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
stdeb.command
✓ python setup.py --command-packages=stdeb.command <command>
stdeb is primarily used via distutils commands specified on the command line, rather than direct Python imports in user code.
pypi-install
✓ pypi-install mypackage
Command-line utility for quick installation from PyPI to a .deb. Use with caution (see warnings).
This quickstart demonstrates how to create a simple Python project with a `setup.py` file and then use `stdeb` to generate a Debian binary package (`.deb`). The resulting `.deb` file will be found in the `deb_dist` directory. This is the recommended approach for creating distributable packages, rather than using `pypi-install` directly.
mkdir my_python_project
cd my_python_project
# Create a dummy setup.py
cat <<EOF > setup.py
from setuptools import setup, find_packages
setup(
name='my-sample-package',
version='0.1.0',
packages=find_packages(),
scripts=['my_script.py'],
description='A simple test package for stdeb.',
author='Example User',
author_email='user@example.com',
install_requires=[],
)
EOF
# Create a dummy script
mkdir my_sample_package
cat <<EOF > my_sample_package/__init__.py
EOF
cat <<EOF > my_sample_package/my_script.py
import sys
def main():
print("Hello from my_sample_package!")
print(f"Running with Python {sys.version_info.major}.{sys.version_info.minor}")
if __name__ == '__main__':
main()
EOF
# Generate a Debian binary package (.deb)
python3 setup.py --command-packages=stdeb.command bdist_deb
echo "\nGenerated .deb file(s) in:"
ls deb_dist/*.deb
py2dsc --version
Debug
Known issues
breakingstdeb has removed support for Python 2.x and now requires Python 3.7 or newer. Additionally, it requires a minimum `debhelper` version of 12 for building Debian packages.fixEnsure you are running stdeb with Python 3.7+ and have `debhelper` version 12+ installed on your system. If generating Python 2 packages, older stdeb versions (0.10.x and below) might still work on a best-effort basis.
affects: 0.11.0+
gotchaThe `pypi-install` command-line utility provides a quick way to convert and install a PyPI package as a `.deb`, but it does not guarantee proper fulfillment of all Debian package dependencies and bypasses customization options. Manual intervention for dependencies is frequently required.fixFor production or customized packages, use the `sdist_dsc` or `bdist_deb` distutils commands (e.g., `python setup.py --command-packages=stdeb.command bdist_deb`) and manually verify/customize the generated `debian/` directory.
affects: All versions
gotchaDebian packages generated by `stdeb` (especially those with extension modules) are highly sensitive to the build environment. Installing a `.deb` on a different Debian/Ubuntu version than where it was compiled can lead to undefined behavior or breakages.fixBuild your `.deb` packages on the exact target distribution and version where they will be installed, or target a stable/oldstable Debian distribution for wider compatibility.
affects: All versions
breakingstdeb relies on extending `distutils` commands via `setup.py`. With Python 3.12+, `distutils` was removed from the standard library. While `setuptools` provides a compatibility shim, direct reliance on `distutils` might lead to future compatibility issues or require specific `setuptools` versions.fixEnsure `setuptools` is installed and up-to-date in your environment. Be aware that the Python packaging ecosystem is evolving beyond `distutils`/`setup.py` towards `pyproject.toml` and other build backends. Monitor stdeb's official channels for updates regarding modern packaging standards.
affects: Potentially Python 3.12+
gotchaWhen using the `debianize` command (or `bdist_deb`), `stdeb` generates a `debian/` directory. The `Build-Depends` in the resulting `debian/control` file often requires manual review and adjustment to correctly specify all necessary system-level and Python package build dependencies.fixAfter running `debianize`, inspect and modify `debian/control` to ensure all build dependencies (especially `python3-all`, `dh-python`, and any other required system libraries or Python packages) are correctly listed.
affects: All versions
gotchaSystem-level packages like `python3-all` (for Python 3 projects) and `dh-python` are often crucial runtime or build dependencies for `stdeb` to function correctly, but might not be explicitly pulled in by `pip install stdeb` alone. Missing these can lead to cryptic build failures.fixBefore using `stdeb`, ensure you install necessary system packages: `sudo apt-get install python3-all debhelper dh-python` (or equivalent for your distribution).
affects: All versions
Upgrade
Version history
0.11.0latest on PyPI · released Sep 12, 2025
Audit
Dependencies
python-debianrequiredCore dependency for Debian packaging utilities.
wheelrequiredUsed in the Python packaging ecosystem for building wheels, which can interact with distutils/setuptools build processes.
setuptoolsrequiredWhile stdeb removed a direct dependency in older versions, it primarily works by extending distutils commands via setup.py, for which setuptools is the de facto standard and provides a distutils shim in Python 3.12+.