{"id":2503,"library":"flake8-docstrings","title":"flake8-docstrings","description":"flake8-docstrings is an extension for the `flake8` linter that integrates `pydocstyle` to enforce PEP 257 docstring conventions and other common docstring styles. It allows developers to check for issues like missing docstrings, incorrect formatting, and adherence to specific style guides (e.g., Google, NumPy) directly within their `flake8` workflow. The current stable version is 1.7.0, and it maintains an active release cadence.","status":"active","version":"1.7.0","language":"en","source_language":"en","source_url":"https://github.com/pycqa/flake8-docstrings","tags":["flake8","linting","docstrings","code quality","pydocstyle","PEP 257"],"install":[{"cmd":"pip install flake8-docstrings","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Core linter that flake8-docstrings extends.","package":"flake8","optional":false},{"reason":"Provides the underlying docstring style checks.","package":"pydocstyle","optional":false}],"imports":[],"quickstart":{"code":"# my_module.py\ndef my_function(arg):\n    \"\"\"This is a missing docstring summary.\n\n    :param arg: An argument.\n    :return: None\n    \"\"\"\n    pass\n\n# Configure in setup.cfg, .flake8, or tox.ini\n# [flake8]\n# docstring-convention = google\n# extend-ignore = D205,D212,D415 # Common ignores for Google style\n\n# Run flake8 from your terminal\n# $ flake8 my_module.py\n","lang":"python","description":"After installation, `flake8-docstrings` automatically integrates with `flake8`. You can run `flake8` as usual. To apply specific docstring conventions (like Google or NumPy style) or to ignore certain checks, configure `flake8` using a configuration file (e.g., `setup.cfg`, `.flake8`, `tox.ini`) under the `[flake8]` section, or via command-line arguments like `--docstring-convention`."},"warnings":[{"fix":"Ensure your project uses Python 3.8 or a newer compatible version. For older Python 3 versions, consider pinning an earlier `flake8-docstrings` version if necessary, though it's recommended to upgrade Python.","message":"Older versions of `flake8-docstrings` (before 1.0.0) supported Python 2.7. Modern versions, including 1.7.0, require Python 3.8 or later.","severity":"breaking","affected_versions":"<1.0.0 (Python 2.7 support), >=1.0.0 (Python 3+), >=1.7.0 (Python 3.8+)"},{"fix":"When debugging docstring issues, refer to `pydocstyle`'s documentation for specific error codes and their meaning. If you believe a check is incorrect, consider checking `pydocstyle`'s issue tracker or reporting there directly.","message":"`flake8-docstrings` acts as a wrapper for `pydocstyle`. While `flake8-docstrings` integrates `pydocstyle` into `flake8`, the actual docstring checks and their error codes (e.g., D100, D205) originate from `pydocstyle`. Issues with specific docstring check logic or behavior should often be reported to the `pydocstyle` project.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Add `docstring-convention = google` (or `numpy`) to your `[flake8]` configuration in `setup.cfg`, `.flake8`, or `tox.ini`. You may also need to `extend-ignore` specific `pydocstyle` codes that conflict with your chosen style.","message":"By default, `pydocstyle` (and thus `flake8-docstrings`) enforces PEP 257. If your project uses other docstring conventions like Google or NumPy style, you must explicitly configure `flake8` with `--docstring-convention google` or `--docstring-convention numpy`. Without this, non-PEP 257 compliant docstrings will trigger many errors.","severity":"gotcha","affected_versions":"All versions"},{"fix":"If using `docstring-convention = all`, carefully review the generated errors and use `extend-ignore` in your `flake8` configuration to disable conflicting or unwanted `pydocstyle` (D-prefixed) codes.","message":"When using `docstring-convention = all` (which enables all `pydocstyle` rules), you might encounter conflicting checks, as `pydocstyle` itself defines some mutually exclusive rules. This will lead to many false positives or undesirable warnings.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-10T00:00:00.000Z","next_check":"2026-07-09T00:00:00.000Z"}