setuptools "error: unknown distribution option" in CI

setuptools parsed your setup() call or setup.cfg and found a keyword it does not recognize. Either the option requires a newer setuptools, or it is provided by a plugin (such as setuptools_scm) that was not installed in the build environment.

What this error means

The build prints "error: unknown distribution option: 'X'" (for example use_scm_version or long_description_content_type on an old setuptools), then stops.

error: unknown distribution option: 'use_scm_version'

Common causes

The option needs a newer setuptools

Options like long_description_content_type only exist on recent setuptools. An old version in the build env does not know the keyword.

A plugin that adds the option is not installed

use_scm_version is registered by setuptools_scm. Without that package in build-system.requires, setuptools sees an unknown option.

How to fix it

Add the plugin or bump setuptools in build requires

1. Identify which package registers the unknown option.
2. Add it (or a newer setuptools) to [build-system] requires.
3. Re-run the isolated build.

[build-system]
requires = ["setuptools>=64", "setuptools_scm>=8", "wheel"]
build-backend = "setuptools.build_meta"

Move config to the supported location

Some keys belong in pyproject.toml [project] or [tool.setuptools] on modern setuptools rather than in setup() kwargs.

[tool.setuptools_scm]
# enables use_scm_version style versioning

How to prevent it

• Pin a minimum setuptools that supports every option you use.
• Declare plugins that add setup options in build-system.requires.
• Migrate static metadata to [project] in pyproject.toml.

Related guides