設定項目

pyproject.tomlで設定する。 このページは設定項目のリファレンスで、最小例 → プリセット設定 → 言語カテゴリゲート → 設定項目一覧 → グローバル設定 → ツール別除外・自動オプション・並列実行などの補助機能、の順に並ぶ。 導入手順ははじめにを参照。

例

[tool.pyfltr]
preset = "latest"
pylint-args = ["--jobs=4"]
extend-exclude = ["foo", "bar.py"]

プリセット設定

プリセットは各時点での推奨ツール構成をバージョン付きで示すスナップショット。 Python / JavaScript / TypeScript / Rust / .NET / ドキュメント系の推奨ツールを横断的に収録する。 "latest"または日付指定（"20260413" / "20260411" / "20260330"）を指定する。

[tool.pyfltr]
preset = "latest"

preset = "latest"はpyfltrの更新に伴って対象ツールの追加や既定値の変更が予告なく入ることがある。 破壊的変更を避ける場合は日付指定プリセットで固定すると、当該日時点の構成をそのまま維持できる。

プリセットでtrueになっているツールも、次節の言語カテゴリキーがゲートを開けた言語分だけが実際に実行される。 preset = "latest" + {language} = trueだけで当該言語の推奨ツール一式が有効化される運用を意図している。

preset "20260413" / "latest"

以下の設定が行われる。

Python核（python = trueで通過）

• ruff-format = true
• ruff-check = true
• mypy = true
• pylint = true
• pyright = true
• pytest = true
• uv-sort = true

JavaScript / TypeScript（javascript = trueで通過）

• eslint = true
• biome = true
• oxlint = true
• prettier = true
• tsc = true
• vitest = true

Rust（rust = trueで通過）

• cargo-fmt = true
• cargo-clippy = true
• cargo-check = true
• cargo-test = true
• cargo-deny = true

.NET（dotnet = trueで通過）

• dotnet-format = true
• dotnet-build = true
• dotnet-test = true

ドキュメント系（カテゴリゲート非対象、常時通過）

• textlint = true
• markdownlint = true
• actionlint = true
• typos = true
• pre-commit = true

preset "20260411"

"20260413"からpre-commit = trueを除いた構成（pre-commitは"20260413"以降で追加）。 それ以外の有効化ツール（Python核・JavaScript / TypeScript・Rust・.NET・ textlint / markdownlint / actionlint / typos / uv-sort）は同一。

preset "20260330"

"20260411"からactionlint = true / typos = true / uv-sort = trueを除いた構成。 Python核・JavaScript / TypeScript・Rust・.NET・textlint・markdownlint・pyrightを有効化する。

言語カテゴリによるゲート制御

各言語カテゴリに属するツールは既定で無効（opt-in）。 プロジェクトで利用する言語カテゴリキーをtrueにすると、プリセットで推奨された当該言語ツールがゲートを通過して有効化される。 カテゴリキーをfalse（既定）にすると、プリセットでtrueになっていてもゲートでfalseに上書きされる。

preset = "latest" + {language} = trueの組み合わせだけで当該言語の推奨ツール一式が有効化される。

個別のツール単位では{command} = trueでの有効化・{command} = falseでの無効化も可能で、 適用優先度はpreset < 言語カテゴリゲート < 個別設定。

[tool.pyfltr]
preset = "latest"
python = true

各言語カテゴリキーとゲート対象ツールは次の通り。

• python: ruff-format・ruff-check・mypy・pylint・pyright・ty・pytest・uv-sort
• javascript: eslint・biome・oxlint・prettier・tsc・vitest（TypeScriptも同一カテゴリ）
• rust: cargo-fmt・cargo-clippy・cargo-check・cargo-test・cargo-deny
• dotnet: dotnet-format・dotnet-build・dotnet-test

カテゴリ同士は独立して作用する。 たとえばpython = trueを指定してもJavaScript系やRust系のツールは有効化されない。 Python系ツール一式は本体依存に同梱されているため、uvx pyfltr単発で利用できる。 JavaScript系・Rust系・.NET系は各言語のツールチェイン（Node.js・cargo・dotnet CLI）が前提となる。

対応するPython系ツールはruff-format / ruff-check / mypy / pylint / pyright / ty / pytest / uv-sortの8種。 このうちtyのみpreset非収録のため、必要に応じて個別にty = trueを指定する（ゲートを越えて最優先）。

[tool.pyfltr]
preset = "latest"
python = true
ty = true        # preset 非収録のため個別指定で追加

設定項目一覧

設定項目と既定値はpyfltr config listで確認できる。 未指定時はpyproject.tomlに明示された値のみを挿入順で表示する。 全キー一覧（既定値のままのキーを含む）を確認するときは--allを付ける。

pyfltr config list --all

--all指定時はDEFAULT_CONFIGを起点にpyproject.toml値をマージし、キー昇順で出力する。 出力形式ごとに既定値か明示値かを区別する。

• text: 既定値の行末に(default)を付加する（明示値には何も付かない）
• json: {"values": {key: {"value": ..., "default": bool}, ...}}の二段構造で返す
• jsonl: 各行にdefault: boolフィールドを追加する

{command}系の項目およびツール固有の項目（prettier-check-argsなど）の詳細はツール別設定ページを参照。

• preset : プリセット設定（前述）
• python : Python系ツールのゲート開閉（前述）
• javascript : JavaScript / TypeScript系ツールのゲート開閉（前述）
• rust : Rust系ツールのゲート開閉（前述）
• dotnet : .NET系ツールのゲート開閉（前述）
• {command} : 各コマンドの有効/無効
• {command}-path : 実行するコマンド
• {command}-args : 追加のコマンドライン引数（lint/fix両モードで常に付与）
• {command}-lint-args : 非fixモードで付与する引数（既定はtextlintのみ["--format", "compact"]）
• {command}-fast : fastサブコマンドに含めるか否か（後述）
• {command}-fix-args : fix段で{command}-argsの後に追加する引数 （既定値はtextlint / markdownlint / ruff-check / eslint / biomeのみ定義）
• {command}-targets : 対象ファイルパターンの完全上書き
• {command}-extend-targets : 対象ファイルパターンへの追加
• {command}-exclude : ツール別の追加除外パターン（後述）
• {command}-pass-filenames : ファイル引数をコマンドに渡すか否か（既定: true）
• {command}-runner : ツール起動方式。 カテゴリ委譲値（"python-runner" / "js-runner" / "bin-runner"）または直接指定値（9種）の対称12値を許容する。 既定値はツールごとに異なる（ツール別設定を参照）
• python-runner : {command}-runner = "python-runner"の解決先（"uv" / "uvx" / "direct"、既定: "uv"）
• js-runner : {command}-runner = "js-runner"の解決先（"pnpx" / "pnpm" / "npm" / "npx" / "yarn" / "direct"、既定: "pnpx"）
• bin-runner : {command}-runner = "bin-runner"の解決先（"mise" / "direct"、既定: "mise"）
• {command}-version : bin-runner対応ツールのバージョン指定（既定: "latest"）
• pylint-pydantic : pylint実行時に--load-plugins=pylint_pydanticを自動追加するか（既定: true、後述）
• mypy-unused-awaitable : mypy実行時に--enable-error-code=unused-awaitableを自動追加するか（既定: true、後述）
• jobs : linters/testersの最大並列数（既定: 4。CLIの-jオプションでも指定可能）
• command-timeout : コマンド単体のタイムアウト秒数のグローバル既定値（既定: 600秒。0で無効化）
• {command}-timeout : per-toolのタイムアウト秒数。未指定時はcommand-timeoutのグローバル値にフォールバックする。 正の秒数を指定すると当該コマンドのみその値で上書きし、0を指定すると当該コマンドのtimeoutのみ無効化する。 内部的には負値を「未指定」のsentinelとして扱うため、誤って負値を設定した場合もグローバル値へフォールバックする
• retry-on-oom : LinuxのOOM killer起因でツールが強制終了された場合に自動リトライするか（既定: true。後述）
• retry-max-attempts : OOM検知時の最大リトライ回数（既定: 1。0でリトライ無効。後述）
• exclude : 除外するファイル名/ディレクトリ名パターン（既定値あり。ロックファイル・minify済みファイル・source mapも含む）
• extend-exclude : 追加で除外するファイル名/ディレクトリ名パターン（既定は空）
• respect-gitignore : .gitignoreに記載されたファイルを除外するか否か（既定: true）。 gitのルートおよびネストした.gitignore、グローバルgitignore、.git/info/excludeを全て考慮する。gitコマンドが必要
• pre-commit-auto-skip : .pre-commit-config.yamlからpyfltr関連hookを自動検出してSKIP環境変数に追加するか（既定: true）
• pre-commit-skip : SKIP環境変数に渡すhook IDの手動指定リスト（pre-commit-auto-skipと併用可能）
• archive : 実行アーカイブの有効/無効（既定: true。--no-archiveで実行単位に無効化）
• archive-max-runs : 保存する最大世代数（既定: 100。0以下で世代軸の自動削除を無効化）
• archive-max-size-mb : アーカイブ全体の合計サイズ上限（既定: 1024 MB。0以下でサイズ軸の自動削除を無効化）
• archive-max-age-days : 保存期間の上限（日数。既定: 30。0以下で期間軸の自動削除を無効化）
• cache : ファイルhashキャッシュの有効/無効（既定: true。--no-cacheで実行単位に無効化）
• cache-max-age-hours : キャッシュエントリの保存期間（時間。既定: 12。0以下で期間軸の自動削除を無効化）
• replace-history-max-entries : replaceサブコマンドの履歴の最大世代数（既定: 100。0以下で世代軸の自動削除を無効化）
• replace-history-max-size-bytes : replace履歴全体の合計サイズ上限（バイト単位。 既定: 200 * 1024 * 1024（約200 MiB）。0以下でサイズ軸の自動削除を無効化）
• replace-history-max-age-days : replace履歴の保存期間の上限（日数。既定: 30。0以下で期間軸の自動削除を無効化）
• jsonl-diagnostic-limit : 1ツールあたりのdiagnostic出力件数上限（既定: 0 = 無制限）
• jsonl-message-max-lines : tool.messageの行数上限（既定: 30）
• jsonl-message-max-chars : tool.messageの文字数上限（既定: 2000）
• textlint-protected-identifiers : textlint fixで破損させてはならない識別子のリスト。 既定値は[".NET", "Node.js", "Vue.js", "Next.js", "Nuxt.js"]。 詳細はツール別設定を参照
• subproject-exclude : モノレポ検出時に走査・サブプロジェクト集合から除外するディレクトリ名の追加リスト。 既定値は空。既定で.venv・node_modules・target・build・dist・.gitは常に除外する
• subproject-use-gitignore : モノレポ検出で.gitignoreを尊重するか否か（既定: true）。 .gitignoreの対象と判定された候補は検出集合から除外する
• subproject-uv-workspace : [tool.uv.workspace] membersを読み取ってサブプロジェクトに含めるか否か（既定: true）
• {command}-subproject-aware : 当該ツールをサブプロジェクト単位で分割実行するか否か（per-tool）。 既定値はビルトイン定義に従う。 mypy・pylint・pytest・textlint等はtrue、typos・shellcheck・shfmt・pre-commit等はfalse

prettier-check-args / prettier-write-args / shfmt-check-args / shfmt-write-argsなどの 2段階実行向け引数はツール別設定ページで詳しく扱う。

OOM自動リトライ

LinuxのOOM killerによってツールプロセスが強制終了された場合、pyfltrは自動的にリトライする。

retry-on-oomをtrue（既定）にすると、ツールのリターンコードが-9または137のときをOOM起因とみなして リトライを試みる。タイムアウト超過によるSIGKILLはOOM起因とはみなさず、リトライの対象外とする。

retry-max-attemptsはOOM検知時の最大リトライ回数を指定する。既定値は1（最大1回リトライ）。 0を指定するとリトライを無効化する（retry-on-oom: falseと同じ効果）。

JSONL出力（--output-format=jsonl）では、commandレコードのretry_countフィールドにリトライ回数が記録される。 retry_countが0のときはフィールド自体が省略される。

Windows環境ではOOM killerが存在せずreturncodeが-9または137にならないため、本機能のリトライは実行されない。

グローバル設定

プロジェクトをまたいで共通にしたい設定（archiveの保持期間やキャッシュ保存期間など）は、 ユーザーレベルのグローバル設定ファイルに書くことでマシン単位で集約できる。

グローバル設定ファイルのパス

OS別のパスは次の通り（platformdirs.user_config_dir("pyfltr")が解決する場所）。

• Linux: ~/.config/pyfltr/config.toml
• macOS: ~/Library/Application Support/pyfltr/config.toml
• Windows: %LOCALAPPDATA%\pyfltr\config.toml

環境変数PYFLTR_GLOBAL_CONFIGを設定するとそのパスを優先する （テスト容易性の確保やユーザーによる強制上書きを目的とした差し替え用。PYFLTR_CACHE_DIRと命名対称）。

書式

pyproject.tomlと同じ形式で、[tool.pyfltr]セクション配下にキーを列挙する。

[tool.pyfltr]
archive-max-age-days = 30
archive-max-size-mb = 2048
cache-max-age-hours = 24

全項目をグローバル設定ファイルに書くことができる。 ただし、archive系とcache系の計6キーのみ特殊仕様で、グローバル設定が優先される。

• archive系（4キー）: archive / archive-max-runs / archive-max-size-mb / archive-max-age-days
• cache系（2キー）: cache / cache-max-age-hours

これらをproject側のpyproject.tomlに書いた場合は警告が出る。 それ以外のキーはproject側が優先されるため、グローバル設定は未設定時のフォールバックとして機能する。

設定の適用順

1. 既定値を生成する
2. グローバル設定とproject設定（pyproject.toml）を読み込み、1つの入力にマージする
3. archive/cache系はマージ時にグローバル側を優先する（project側に同じキーがあっても上書きされる）
4. それ以外のキーは後勝ち（project側が優先）
5. マージ結果にプリセット（preset）を反映する
6. 言語カテゴリゲート（python / javascript / rust / dotnet）を適用する

適用優先度はpreset < 言語カテゴリゲート < 個別設定。 pyproject.tomlが存在しないディレクトリでもグローバル設定は反映される。

設定操作

pyfltr configサブコマンドを使うと、project側のpyproject.tomlとglobal側のconfig.tomlの 両方をCLIから直接操作できる。 --globalの有無で対象ファイルを切り替える。 詳細はCLIコマンドを参照。

不正な設定値の取り扱い

設定ファイル（pyproject.tomlおよびグローバル設定）で未知のキー・型不一致・許容外の値・削除済みコマンド向けのキーを 検出した場合、該当キーを無視して既定値で処理を続行する。検出内容は警告として記録する。

本挙動は複数バージョンのpyfltrが同じ設定ファイルを参照する状況で、 新しいバージョンが追加したキーを旧バージョンが読み込んだ際の停止を回避するために採用する。 コマンドラインからの設定上書き（--config=key=value等）は対象外で、従来通りエラーで停止する。

ツール別除外設定

{command}-excludeを設定すると、特定ツールにのみ適用する追加の除外パターンを指定できる。 全体のexclude/extend-excludeによる除外はこれとは独立して事前に適用される。

[tool.pyfltr]
# mypy だけ vendor/ と gen_*.py を除外する
mypy-exclude = ["vendor", "gen_*.py"]

パターンの書式はextend-excludeと同じflake8風のglobパターンで、ディレクトリ指定はその配下も除外される。 --no-excludeを指定した場合、全体のexclude/extend-excludeと合わせてツール別除外も無効化される。

pass-filenames = falseのツール（tsc・cargo-*・dotnet-*など）はファイル名をコマンドに渡さないため、 {command}-excludeを設定しても効果がない。

自動オプション

各ツールの望ましいオプションを自動的にコマンドラインに追加する。 {command}-argsとは独立して動作する。

設定	既定	自動追加される引数
pylint-pydantic	true	--load-plugins=pylint_pydantic
mypy-unused-awaitable	true	--enable-error-code=unused-awaitable

自動引数は{command}-argsやCLI引数と重複しないよう排除される。 不要な場合はfalseに設定する。

[tool.pyfltr]
pylint-pydantic = false
mypy-unused-awaitable = false

並列実行

linters/testersはjobsで指定した並列数で実行される（既定: 4）。

[tool.pyfltr]
jobs = 8

CLIオプション-jでも指定でき、pyproject.tomlより優先される。

実行順はfastフラグに基づいて最適化され、fast = falseのツール（mypy、pylint、pytest等）が先に開始される。

fastエイリアス

fastサブコマンドで実行されるコマンドは、各コマンドの{command}-fast設定で制御される。

[tool.pyfltr]
# mypyをfastに追加
mypy-fast = true
# textlintをfastから除外
textlint-fast = false

カスタムコマンドもfast = trueでfastエイリアスに追加できる。

出力順序

非TUIモード（--no-ui、--ci、または非対話端末）では、既定で全コマンドの完了後に 成功コマンド詳細 → 失敗コマンド詳細 → summaryの順でまとめて出力する。 pyfltr ... | tail -Nのようにパイプで末尾だけ切り出してもsummaryと失敗情報が末尾に残るため、 Claude Codeなど末尾だけを読み取るツールでも実行結果を把握できる。

従来の「各コマンドの完了時に即座に詳細ログを出力する」挙動を使いたい場合は--streamを指定する。

---

個別のツール設定（2段階実行、ファイルパターン、直接実行 / js-runner / bin-runnerのカテゴリ別設定、 mise-auto-trustによるmise未信頼の自動対応、カスタムコマンド等）の詳細はツール別設定を参照。