setup.cfg・とは？初心者向けガイド：Pythonパッケージ設定を解説共起語・同意語・対義語も併せて解説！

この記事を書いた人

高岡智則

年齢：33歳性別：男性職業：Webディレクター（兼ライティング・SNS運用担当）居住地：東京都杉並区・永福町の1LDKマンション出身地：神奈川県川崎市身長：176cm 体系：細身〜普通（最近ちょっとお腹が気になる）血液型：A型誕生日：1992年11月20日最終学歴：明治大学・情報コミュニケーション学部卒通勤：京王井の頭線で渋谷まで（通勤20分）家族構成：一人暮らし、実家には両親と2歳下の妹恋愛事情：独身。彼女は2年いない（本人は「忙しいだけ」と言い張る）

setup.cfg・とは？

setup.cfg・とは？というと、Pythonのプロジェクトにおける「設定ファイル」の一つです。設定ファイルは、プロジェクトの名前やバージョン、必要な依存関係などをパッケージ化する際に使われる情報をまとめておく場所。INI形式は見た目がシンプルで、初心者にも読みやすい特徴があります。

主に「パッケージを作る人」が使うもので、setup.py という別ファイルと組み合わせて使われることが多いですが、setup.cfg のみで完結させる方法もあります。現代のPythonパッケージでは pyproject.toml の使用が推奨されるケースも増えています。setup.cfg は長い間使われてきた実績があり、多くの開発現場でまだ現役です。

setup.cfgの基本的な役割

setup.cfg の基本的な役割は、パッケージのメタ情報（名前・バージョン・説明など）と、インストール時に必要な情報（依存関係・パッケージの探索方法など）を定義することです。これにより、コマンドを実行するだけで、どの依存関係を入れるべきか、どのファイルを配布の対象にするべきかが決まります。

代表的なセクションとキー

[metadata] セクションには name、version、description、author などの情報を置きます。

[options] セクションには packages、install_requires、python_requires など、配布時の挙動を決める設定を置きます。

設定の具体例

以下は、実際によく使われる setup.cfg の例です。フルサイズではなく、最小限の内容を示します。

セクション	キー	説明
[metadata]	name, version	パッケージの名前とバージョンを指定します。
[options]	packages, install_requires	配布に含めるパッケージと依存関係を定義します。
[options.extras_require]	dev, tests	追加の依存関係をグループ化します。
[tool.setuptools]	dist-dir	出力先ディレクトリを指定します。

実際の例を以下に示します。この例は最小限の内容ですが、実践では description や classifiers、license なども追加します。コードブロックではなく、見やすいように表現します。

例	内容
[metadata]	name = sample_project
	version = 0.1.0
	description = サンプルプロジェクト
[options]	packages = find:
	install_requires = numpy>=1.21, requests

このように setup.cfg によって、パッケージの作成時に必要な情報が整理され、自動的に依存関係を解決する手助けをしてくれます。

setup.cfgとpyproject.tomlの関係

現在は pyproject.toml の使用が推奨される場面が増えています。pyproject.toml はビルドツールの設定も統一的に管理でき、ビルドシステムの情報を定義します。setup.cfg は補助的な設定や、一部のツールの設定として残っているケースが多いです。つまり、setup.cfg は「設定の1部」を担い、pyproject.toml が「ビルド全体の設定」を担うという役割分担に近くなっています。

初めて setup.cfg を触るときのポイント

1) プロジェクトのルートに setup.cfg を置く。名前は setup.cfg のままにします。
2) INI 形式でセクションを作り、必要なキーを埋める。
3) setup.py や他のツールと組み合わせて、実際にパッケージを作る。
4) 変更多い場合は pyproject.toml への移行を検討する。

設定を追いかけると、どこで何が決まるのか見えやすくなります。最初は基本だけを覚え、徐々に追加のキーを覚えると良いでしょう。

setup.cfgの同意語

設定ファイル: ソフトウェアやパッケージの挙動を決める設定を格納するファイルの総称。setup.cfgはその一種。
INIファイル: 先頭が [セクション] 形式でキーと値を配置する設定ファイル。setup.cfgはこのINI形式で書かれることが多い。
INI形式の設定ファイル: INIフォーマットで記述された設定ファイル。setup.cfgはこの形式で書かれることが多い。
構成ファイル: システムやアプリの動作条件を定義するファイル。setup.cfgもその一つの例です。
プロジェクト設定ファイル: 特定のプロジェクトの設定情報を集約して記述するファイル。setup.cfgはPythonプロジェクトの設定に使われます。
Pythonの設定ファイル: Python関連のツールやパッケージの設定をまとめたファイル。setup.cfgはその用途の一つです。
setuptoolsの設定ファイル: setuptoolsというPythonパッケージの動作を制御する設定を格納。setup.cfgはこの用途で頻出します。
パッケージ設定ファイル: パッケージのビルド・配布時の設定情報を格納するファイル。setup.cfgは代表例です。
ビルド設定ファイル: ビルドやパッケージ作成時のオプションを指定するファイル。setup.cfgも同様の役割を持ちます。
設定テンプレート: 設定のひな形となるファイル。setup.cfgの初期構成として用いられることがあります。
Pythonプロジェクトの構成ファイル: Pythonプロジェクトの挙動を決める設定を集めたファイル。setup.cfgはこのカテゴリに該当します。
設定ファイル（INI形式）: INI形式で記述された設定ファイル。setup.cfgはこの形式で主に用いられます。

setup.cfgの対義語・反対語

未設定: 設定が一切行われていない状態。setup.cfgのような設定ファイルが使われていない状況を指す。
デフォルト設定: 設定を変更せず、ソフトウェアの初期値だけが使われる状態。設定ファイルを使わない場合の対極的なイメージ。
手動設定: 設定をファイルとして用意せず、利用者が直接コード内で設定を行う方法。
コード内設定: 設定値をプログラムのソースコード内に直接埋め込むこと。設定ファイルを使わない対比。
設定ファイルなし: 設定ファイルそのものが存在しない、もしくは使われていない状態。
環境変数設定: 設定を環境変数で行う方法。setup.cfgの代替的な設定手段として捉えた対抗語。
他形式の設定: 設定をINI以外の形式（例：JSON、YAML、XML）で管理すること。
自動設定の状態: ソフトウェアが自動的に設定値を決定する状態で、手動の設定ファイルを必要としない。
リセット状態: すべての設定を初期値に戻した状態。新たな設定ファイルを使わずに初期化するイメージ。
無設定ファイルモード: 設定ファイルを全く用いずに動作するモード。
設定を継承する環境: 設定をこのファイルに依存せず、環境や他の場所から継承する状態。

setup.cfgの共起語

setup.py: Pythonパッケージのビルド・配布を定義するスクリプト。setuptools の setup() で名前・バージョン・依存関係などを指定します。
pyproject.toml: ビルドシステムの設定を記述するファイル。PEP 518/517 に対応し、ビルドツールの設定を統一します。
metadataセクション: パッケージの基本情報を記述するセクション。name、version、author、license、description などが含まれます。
optionsセクション: パッケージの配布時のオプションを設定するセクション。install_requires、python_requires、packages などを指定します。
name: パッケージの名前。配布時の識別子として使われます。
version: パッケージのバージョン番号。例: 1.0.0
description: パッケージの短い説明。
long_description: パッケージの長い説明。通常は README を参照して記述します。
long_description_content_type: long_description の内容タイプ（例: text/markdown）を指定します。
url: パッケージの公式サイトやリポジトリのURL。
author: 著者名。
license: ライセンス情報。例: MIT、Apache-2.0。
classifiers: パッケージの分類を表すリスト。Pythonのバージョンや用途を示します。
install_requires: このパッケージが依存する他のパッケージのリスト。バージョン指定も可能。
python_requires: このパッケージが動作する Python の最低/最高バージョンを指定します。
packages: 同梱するパッケージの候補を検出・列挙します。
include_package_data: パッケージデータをビルドに含めるかどうかを指定します。
exclude_package_data: 含めないデータを明示します。
package_dir: パッケージのソースディレクトリを指定します。
package_data: 特定ファイルをパッケージに含める設定。
extras_require: 追加機能（オプション依存関係）を定義します。
bdist_wheelセクション: wheelパッケージを作成する際のビルドオプションを配置するセクション。
wheel: wheelに関する設定。
flake8設定: コード品質チェックツール Flake8 の設定セクション。max_line_length などを指定します。
max_line_length: 1行の最大文字数を制限します。
ignore: Flake8 で無視する警告のルールを指定します。
isort設定: インポートの整形ツール isort の設定セクション。
line_length: isort の整形時の行長を設定します。
addopts: pytest の追加オプションを指定します。
testpaths: テストを実行するディレクトリ・ファイルを指定します。
pytest ini_options設定: pytest の設定を記述するセクション（例: addopts、testpaths、markers など）。
markers: pytest のマーカー設定を定義します。
coverage:run設定: カバレッジ計測の実行設定を行います。
branch: ブランチカバレッジの計測を有効にするかなどを指定します。
coverage:report設定: カバレッジレポートの出力・表示設定を行います。
show_missing: 欠落しているテストの表示を有効にします。

setup.cfgの関連用語

setup.cfg: Python プロジェクトにおける設定ファイルの一つ。setup.py と併用して、パッケージのメタデータ・依存関係・ビルド設定などを ini 形式で記述します。
setup.py: Python パッケージをビルド・インストールするための実行スクリプト。setup() を呼び出して設定を伝え、setup.cfg の情報を補完します。
setuptools: Python のパッケージ作成・配布ツール。setup.cfg の設定を解釈してパッケージを作成・配布します。
distutils: 古いパッケージ作成ライブラリ。現在は setuptools が主流となり、setup.cfg は主に setuptools 系の設定に使われます。
INI形式: setup.cfg が採用する設定ファイルの形式。セクションは [section]、キー=value の組み合わせで構成されます。
[metadata]: setup.cfg のセクションの一つ。パッケージ名・バージョン・著者などの基本情報を定義します。
name: パッケージの正式な名前。例: mylibrary。
version: パッケージのバージョン番号。例: 1.0.0。
description: パッケージの短い説明文。
long_description: パッケージの長い説明。README などを参照して記述することが一般的です。
long_description_content_type: long_description のマークアップ形式を指定。例: text/markdown。
url: パッケージの公式サイトやリポジトリの URL。
author: 著者名。
author_email: 著者のメールアドレス。
license: ライセンスの種別。
classifiers: パッケージの分類コード。互換性・対象バージョン・サポート OS などを表します。
keywords: 検索時に使われるキーワードのリスト。
project_urls: 追加の公式リンクを辞書形式で設定します（例: Documentation や Source Code など）。
[options]: setup.cfg の主要セクション。依存関係・パッケージの包含方法・ビルド設定などを指定します。
install_requires: このパッケージが依存する他のパッケージのリスト。
python_requires: サポートする Python バージョンを指定します（例: >= 3.8）。
packages: 含めるパッケージのリストまたは自動検出の指定。
package_dir: パッケージのディレクトリ構成を指定します。例: {"": "src"}。
include_package_data: パッケージにデータファイルを含めるかどうかを指定します。
exclude_package_data: 含めないデータファイルを指定します。
setup_requires: ビルド時に必要な追加の依存関係を指定します。
data_files: 追加データファイルを特定の場所へ配置する設定。
[options.packages.find]: packages.find の設定を行うセクション。where などで探索場所を指定します。
where: packages.find の探索ディレクトリ。
[options.extras_require]: extras_require の設定を行うセクション。
extras_require: 機能追加ごとの依存関係を定義します。
[entry_points]: コマンドラインツールなどのエントリポイントを定義するセクション。
console_scripts: 実行可能なコマンドを定義するエントリポイントの例。
[bdist_wheel]: wheel のビルド設定を行うセクション。
wheel: wheel 形式の配布パッケージに関する設定。
[flake8]: flake8 の設定を記述するセクション。
flake8: コード品質・スタイルをチェックするツールの設定。
[mypy]: mypy の設定を記述するセクション。
mypy: 静的型検査ツール。
[isort]: isort の設定を記述するセクション。
isort: import 文の並び順を自動整形するツール。
[pytest]: pytest の設定を記述するセクション。
pytest: Python のユニットテストフレームワーク。
[tool.pytest.ini_options]: pytest の設定を setup.cfg 風に書く場合のセクション名。
pyproject.toml: 新しい設定ファイル形式。PEP 518/621 の準拠で推奨され、setup.cfg の代替・補完として使われます。
configparser: INI ファイルを読み書きする Python の標準ライブラリ。setup.cfg の読み込み処理にも関わります。
PEP 621: Python パッケージのメタデータを pyproject.toml で定義する仕様。将来の標準化動向。
zip_safe: パッケージを ZIP 形式で配布して良いかを示すオプション。
download_url: 古い情報。現在は非推奨のケースが多く、主に参考情報として扱われます。