Install & Compatibility
Where this runs
tested against v1.1.1 · 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.95 runs
installs and imports cleanly · install 0.0s · import 0.086s · 18.8MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.6s · import 0.076s · 19MB
17MB installed
● package 17MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Changelog
✓ from debian.changelog import Changelog
For parsing and manipulating debian/changelog files.
Deb822
✓ from debian.deb822 import Deb822
For parsing and manipulating RFC822-style control files (e.g., debian/control, Packages, Sources).
DebFile
✓ from debian.debfile import DebFile
For read-only access to raw .deb and .ar files.
Version
✓ from debian.debian_support import Version
For basic Debian version string validation. For robust version comparison respecting Debian policy, `python-apt` is often preferred.
This quickstart demonstrates how to parse a `debian/control` file using the `Deb822` module, which treats RFC822-style control data as a dictionary-like object, allowing easy access to package metadata.
from debian.deb822 import Deb822
# Example content of a debian/control file
control_content = """\
Package: my-package
Version: 1.0-1
Section: python
Priority: optional
Architecture: all
Depends: python3, python3-some-dependency (>= 1.2)
Description: A sample Python package.
This is a longer description for the sample package.
"""
# In a real scenario, you'd open a file:
# with open("debian/control", "r") as f:
# control_data = Deb822(f)
# For this quickstart, we use the string directly
control_data = Deb822(control_content.splitlines())
print(f"Package: {control_data['Package']}")
print(f"Version: {control_data['Version']}")
print(f"Dependencies: {control_data.get('Depends', 'N/A')}")
# The Deb822 object behaves like a dictionary
print("\nAll control fields:")
for key, value in control_data.items():
print(f" {key}: {value}")
Debug
Known issues
breakingThe `python-debian` library explicitly requires Python >=3.7. Attempting to use it with Python 2 will result in `SyntaxError` or `ImportError`. Debian 11 (Bullseye) and later have removed the default `python` symlink, requiring explicit use of `python3` for scripts.fixEnsure your environment uses Python 3.7 or newer. Always invoke scripts with `python3` or manage dependencies within a virtual environment.
affects: <1.0.0 (Python 2.x versions of related Debian tools), >=1.0.0 (Python 3.x only)
gotchaFor robust Debian package version comparisons and other `apt`-related functionalities, the `python-apt` library is often preferred over `debian.debian_support.Version`. While `debian.debian_support.Version` provides basic validation, `python-apt` offers full compliance with Debian's policy manual for version comparisons.fixFor comprehensive package management tasks, consider using `python-apt`. If only basic validation is needed, `debian.debian_support.Version` is sufficient. Install `python-apt` separately if its functionality is required (e.g., `pip install python-apt`).
affects: All versions
gotchaWhen developing on Debian systems, be mindful of potential conflicts between system-installed Python packages (in `dist-packages`) and packages installed via `pip` (in `site-packages`). This can lead to unexpected behavior or missing dependencies.fixAlways use Python virtual environments (`venv` or `conda`) for your projects to isolate dependencies and prevent interference with system packages.
affects: All versions, especially on Debian-based systems.
deprecatedOlder versions of Debian provided a `python` command that typically pointed to Python 2. With Debian 11 (Bullseye) and newer, Python 2 has been removed, and the `python` symlink no longer exists by default.fixExplicitly use `python3` when invoking Python scripts or interpreters. For compatibility with legacy scripts that expect a `python` command, install `python-is-python3` or `python-is-python2` (though the latter is discouraged due to Python 2 EOL).
affects: Debian 11 (Bullseye) and later distributions.
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'debian'
The 'python-debian' package is not installed in the Python environment, or the environment is not correctly activated. The library's main module is named 'debian', not 'python_debian'.
fixInstall the package using pip: `pip install python-debian`
ImportError: cannot import name 'Changelog' from 'debian'
The 'Changelog' class (and similar specific classes/functions) resides within a submodule like 'debian.changelog', not directly under the top-level 'debian' package.
fixImport 'Changelog' from its specific submodule: `from debian.changelog import Changelog`
expected a file-like object, not str
Constructors like `debian.deb822.Deb822` (and others) expect a file-like object (e.g., from `open()`, `io.StringIO`) as input, but a plain string was provided directly.
fixWrap the string input in an `io.StringIO` object to simulate a file, or ensure you pass an actual file handle:
```python
import io
from debian import deb822
control_data_str = "Package: example\nVersion: 1.0"
control_file_like = io.StringIO(control_data_str)
control = deb822.Deb822(control_file_like)
```
debian.changelog.ChangelogError: Invalid Changelog format
The input data provided to the `debian.changelog.Changelog` parser does not adhere to the expected Debian changelog file format specification, leading to a parsing failure.
fixVerify that the input string or file content strictly follows the Debian changelog format, or implement robust error handling (e.g., `try-except`) if parsing potentially malformed or untrusted data.
Upgrade
Version history
1.1.1latest on PyPI · released Jun 7, 2026
Audit
Dependencies
python-aptoptionalOptional dependency to speed up certain processing, particularly related to Debian package version comparisons.