pubspec ファイル

目次 keyboard_arrow_down keyboard_arrow_up

more_horiz

すべての pub パッケージには、依存関係を指定するためにいくつかのメタデータが必要です。他のユーザーと共有される Pub パッケージには、ユーザーがそれらを発見できるように、その他の情報も提供する必要があります。これらのメタデータはすべて、パッケージの pubspec:、すなわち YAML 言語で記述された pubspec.yaml という名前のファイルに格納されます。

pubspec には以下のフィールドを含めることができます。

name: すべてのパッケージで必須です。詳細はこちら。
version: pub.dev サイトでホストされるパッケージで必須です。詳細はこちら。
description: pub.dev サイトでホストされるパッケージで必須です。詳細はこちら。
homepage: オプション。パッケージのホームページ（またはソースコードリポジトリ）を指す URL。詳細はこちら。
repository: オプション。パッケージのソースコードリポジトリを指す URL。詳細はこちら。
issue_tracker: オプション。パッケージの Issue tracker を指す URL。詳細はこちら。
documentation: オプション。パッケージのドキュメントを指す URL。詳細はこちら。
dependencies: パッケージに依存関係がない場合は省略できます。詳細はこちら。
dev_dependencies: パッケージに開発依存関係がない場合は省略できます。詳細はこちら。
dependency_overrides: 依存関係をオーバーライドする必要がない場合は省略できます。詳細はこちら。
environment: Dart 2 以降で必須です。詳細はこちら。
executables: オプション。パッケージの実行可能ファイルを PATH に配置するために使用されます。詳細はこちら。
platforms: オプション。pub.dev サイトでサポートされるプラットフォームを明示的に宣言するために使用されます。詳細はこちら。
publish_to: オプション。パッケージの公開先を指定します。詳細はこちら。
funding: オプション。パッケージの開発をスポンサーできる URL のリスト。詳細はこちら。
false_secrets: オプション。機密情報の漏洩の可能性を公開前の検索で無視するファイルを指定します。詳細はこちら。
screenshots: オプション。pub.dev サイトに表示するスクリーンショットファイルのリストを指定します。詳細はこちら。
topics: オプション。パッケージのトピックのリスト。詳細はこちら。
ignored_advisories: オプション。無視するセキュリティアドバイザリのリスト。詳細はこちら。

Pub は他のすべてのフィールドを無視します。

カスタムフィールドを追加する場合は、将来の pubspec フィールドと衝突しない一意の名前を付けます。たとえば、bugs を追加する代わりに、my_pkg_bugs という名前のフィールドを追加するかもしれません。

シンプルで完全な pubspec は、以下のようなものになります。

yamlname: newtify
description: >-
  Have you been turned into a newt?  Would you like to be?
  This package can help. It has all of the
  newt-transmogrification functionality you have been looking
  for.
version: 1.2.3
homepage: https://example-pet-store.com/newtify
documentation: https://example-pet-store.com/newtify/docs

environment:
  sdk: '^3.2.0'
  
dependencies:
  efts: ^2.0.4
  transmogrify: ^0.4.0
  
dev_dependencies:
  test: '>=1.15.0 <2.0.0'

このセクションでは、pubspec の各フィールドについてさらに詳しく説明します。

すべてのパッケージには名前が必要です。これは、他のパッケージがあなたのパッケージを参照する方法であり、公開した場合の世界に表示される方法です。

名前はすべて小文字で、単語を区切るにはアンダースコアを使用し、just_like_this のようにします。基本的なラテン文字とアラビア数字のみを使用してください: [a-z0-9_]。また、名前は有効な Dart 識別子であることを確認してください。つまり、数字で始まらず、予約語ではないようにしてください。

明確で簡潔で、すでに使用されていない名前を選択するようにしてください。pub.dev サイトでパッケージを簡単に検索して、他に誰もあなたの名前を使用していないことを確認することをお勧めします。

すべてのパッケージにはバージョンがあります。バージョン番号は pub.dev サイトにパッケージをホストするために必要ですが、ローカル専用のパッケージでは省略できます。省略した場合、パッケージは暗黙的にバージョン 0.0.0 となります。

バージョン管理は、コードを再利用しながら急速に進化させるために必要です。バージョン番号は、0.2.43 のように、ドットで区切られた 3 つの数字です。オプションで、ビルド (+1、+2、+hotfix.oopsie) またはプレリリース (-dev.4、-alpha.12、-beta.7、-rc.5) のサフィックスを含めることもできます。

パッケージを公開するたびに、特定のバージョンで公開します。一度公開されると、それは変更不可と見なされます。さらに変更を行うには、新しいバージョンが必要です。

バージョンを選択する際は、セマンティックバージョニングに従ってください。

これは個人のパッケージではオプションですが、パッケージを公開するつもりであれば、英語で記述された説明を提供する必要があります。説明は比較的短く（60〜180文字）、カジュアルな読者にとってパッケージについて知っておくと良いことを伝えるべきです。

説明は、パッケージのセールストークと考えてください。ユーザーはパッケージを閲覧する際にこれを目にします。説明はプレーンテキストであり、Markdown や HTML は使用できません。

これはパッケージの Web サイトを指す URL であるべきです。ホストされたパッケージの場合、この URL はパッケージのページからリンクされます。homepage を提供することはオプションですが、提供してください、または repository (またはその両方) を提供してください。これにより、ユーザーはパッケージの出所を理解しやすくなります。

オプションの repository フィールドには、パッケージのソースコードリポジトリの URL を含めるべきです。たとえば、https://github.com/<user>/<repository> のようなものです。パッケージを pub.dev サイトに公開する場合、パッケージのページにリポジトリ URL が表示されます。repository を提供することはオプションですが、提供してください、または homepage (またはその両方) を提供してください。これにより、ユーザーはパッケージの出所を理解しやすくなります。

オプションの issue_tracker フィールドには、パッケージの Issue tracker への URL を含めるべきです。ここでは、既存のバグを表示したり、新しいバグを提出したりできます。pub.dev サイトは、このフィールドの値を使用して、各パッケージの Issue tracker へのリンクを表示しようとします。issue_tracker が欠落していて repository が存在し、GitHub を指している場合、pub.dev サイトはデフォルトの Issue tracker (https://github.com/<user>/<repository>/issues) を使用します。

一部のパッケージには、Pub が生成する API リファレンスやメインのホームページとは別に、ドキュメントをホストするサイトがあります。パッケージにドキュメントがある場合は、その URL を持つ documentation: フィールドを追加します。pub は、パッケージのページにこのドキュメントへのリンクを表示します。

依存関係は、pubspec のraison d'être（存在理由）です。このセクションでは、パッケージが機能するために必要な各パッケージをリストします。

依存関係は 2 つのタイプに分類されます。通常の依存関係 は dependencies: の下にリストされます。これらは、パッケージを使用するすべての人が必要とするパッケージです。パッケージ自体の開発段階でのみ必要な依存関係は、dev_dependencies の下にリストされます。

開発プロセス中に、依存関係を一時的にオーバーライドする必要がある場合があります。これは dependency_overrides を使用して行うことができます。

詳細については、パッケージの依存関係を参照してください。

パッケージは、スクリプトの 1 つ以上を実行可能ファイルとして公開し、コマンドラインから直接実行できるようにすることができます。スクリプトを一般公開するには、executables フィールドの下にリストします。エントリはキー/値のペアとしてリストされます。

<name-of-executable>: <Dart-script-from-bin>

たとえば、次の pubspec エントリは 2 つのスクリプトをリストしています。

yamlexecutables:
  slidy: main
  fvm:

パッケージが dart pub global activate を使用してアクティブ化されると、slidy と入力すると bin/main.dart が実行されます。fvm と入力すると bin/fvm.dart が実行されます。値が指定されていない場合、キーから推測されます。

詳細については、pub global を参照してください。

パッケージを公開すると、pub.dev はパッケージがサポートするプラットフォームを自動的に検出します。このプラットフォームサポートリストが正しくない場合は、platforms を使用して、パッケージがサポートするプラットフォームを明示的に宣言します。

たとえば、次の platforms エントリにより、pub.dev はパッケージが Android、iOS、Linux、macOS、Web、Windows をサポートしていると表示されます。

yaml# This package supports all platforms listed below.
platforms:
  android:
  ios:
  linux:
  macos:
  web:
  windows:

パッケージが Linux と macOS のみ（たとえば Windows は含まない）をサポートすることを宣言する例を次に示します。

yaml# This package supports only Linux and macOS.
platforms:
  linux:
  macos:

デフォルトはpub.dev サイトを使用します。パッケージの公開を防止するには none を指定します。この設定は、カスタム pub パッケージサーバーに公開するために使用できます。

yaml

publish_to: none

パッケージ作成者は、funding プロパティを使用して、ユーザーがパッケージの開発にどのように資金提供できるかに関する情報を提供する URL のリストを指定できます。たとえば、次のようになります。

yamlfunding:
 - https://www.buymeacoffee.com/example_user
 - https://www.patreon.com/some-account

pub.dev に公開された場合、リンクはパッケージページに表示されます。これは、ユーザーが依存関係の開発に資金提供するのを助けることを目的としています。

パッケージを公開しようとすると、pub は機密情報、API キー、または暗号化キーの潜在的な漏洩を検索します。公開されるファイルに潜在的な漏洩が検出された場合、pub は警告を発し、パッケージの公開を拒否します。

漏洩検出は完璧ではありません。誤検知を回避するために、pubspec の false_secrets の下にある gitignore パターンを使用して許可リストを作成することで、特定のファイルでの漏洩検索を pub に指示しないようにできます。

たとえば、次のエントリは、ファイル lib/src/hardcoded_api_key.dart および test/localhost_certificates/ ディレクトリ内のすべての .pem ファイルでの漏洩を pub が検索しないようにします。

yamlfalse_secrets:
 - /lib/src/hardcoded_api_key.dart
 - /test/localhost_certificates/*.pem

gitignore パターンをスラッシュ (/) で開始すると、パターンがパッケージのルートディレクトリからの相対パスとして扱われることが保証されます。

パッケージは、pub.dev ページに表示されるスクリーンショットを使用して、ウィジェットやその他の視覚的要素をアピールできます。パッケージが表示するスクリーンショットを指定するには、screenshots フィールドを使用します。

パッケージは、screenshots フィールドの下に最大 10 枚のスクリーンショットをリストできます。このセクションにロゴやその他のブランドイメージを含めないでください。各スクリーンショットには、1 つの description と 1 つの path が含まれます。description は、スクリーンショットが何を表しているかを 160 文字以内で説明します。たとえば、次のようになります。

yamlscreenshots:
  - description: 'This screenshot shows the transformation of a number of bytes 
  to a human-readable expression.'
    path: path/to/image/in/package/500x500.webp
  - description: 'This screenshot shows a stack trace returning a human-readable
  representation.'
    path: path/to/image/in/package.png

Pub.dev はスクリーンショットを次の仕様に制限します。

ファイルサイズ: 画像あたり最大 4 MB。
ファイルタイプ: png、jpg、gif、または webp。
静止画像とアニメーション画像のどちらも許可されます。

スクリーンショットファイルは小さく保ちます。パッケージの各ダウンロードには、すべてのスクリーンショットファイルが含まれます。

Pub.dev は、最初のスクリーンショットからパッケージのサムネイル画像を生成します。このスクリーンショットがアニメーションを使用している場合、pub.dev はその最初のフレームを使用します。

パッケージ作成者は、topics フィールドを使用してパッケージを分類できます。トピックは、pub.dev での検索中に検索を支援するために使用できます。Pub.dev は、パッケージページおよび検索結果にトピックを表示します。

このフィールドは、名前のリストで構成されます。たとえば、次のようになります。

yamltopics:
  - network
  - http

Pub.dev は、トピックを次の仕様に従うことを要求します。

各パッケージには最大 5 つのトピックをタグ付けします。
トピック名を次の要件に従って記述します。
- 2 文字から 32 文字を使用します。
- 小文字の英数字またはハイフン (a-z、0-9、-) のみを使用します。
- 連続するハイフン (--) は使用しないでください。
- 名前は小文字のアルファベット文字 (a-z) で開始します。
- 英数字 (a-z または 0-9) で終了します。

トピックを選択する際は、既存のトピックが関連性があるかどうかを検討してください。既存のトピックにタグを付けることは、ユーザーがパッケージを発見するのに役立ちます。

パッケージにセキュリティアドバイザリの影響を受ける依存関係がある場合、pub は依存関係の解決中にアドバイザリについて警告します。パッケージ作成者は、ignored_advisories フィールドを、パッケージに関連しないトリガーされたアドバイザリの許可リストとして使用できます。

アドバイザリに関する警告を抑制するには、アドバイザリ識別子を ignored_advisories リストに追加します。たとえば、次のようになります。

yamlname: myapp
dependencies:
  foo: ^1.0.0
ignored_advisories:
 - GHSA-4rgh-jx4f-qfcq

詳細については、セキュリティアドバイザリを参照してください。

パッケージは、依存関係のどのバージョンをサポートするかを示すことができますが、パッケージには別の暗黙の依存関係があります: Dart プラットフォーム自体です。Dart プラットフォームは進化しており、パッケージはプラットフォームの特定のバージョンでのみ機能する場合があります。

パッケージは、*SDK 制約*を使用してこれらのバージョンを指定できます。この制約は、pubspec の別のトップレベルの environment フィールド内に配置され、依存関係と同じバージョン制約構文を使用します。

たとえば、次の制約は、このパッケージがバージョン 3.0.0 以降の任意の Dart SDK で動作することを示しています。

yamlenvironment:
  sdk: ^3.0.0

Pub は、インストールされている Dart SDK のバージョンと互換性のあるパッケージの最新バージョンを見つけようとします。

SDK 制約を省略するとエラーになります。pubspec に SDK 制約がない場合、dart pub get は以下のようなメッセージで失敗します。

pubspec.yaml has no lower-bound SDK constraint.
You should edit pubspec.yaml to contain an SDK constraint:

environment:
  sdk: '^3.2.0'
  
See https://dart.dokyumento.jp/go/sdk-constraint

Pub は environment: フィールドの下に Flutter SDK 制約を指定することをサポートしています。

yamlenvironment:
  sdk: ^3.2.0
  flutter: '>=3.22.0'

Flutter SDK 制約は、pub が flutter 実行可能ファイルのコンテキストで実行されており、Flutter SDK の version ファイルがバージョン制約の下限を満たしている場合にのみ満たされます。それ以外の場合、パッケージは選択されません。

Flutter SDK 制約を持つパッケージを公開するには、古いバージョンの pub が Flutter を必要とするパッケージを誤ってインストールしないように、最低バージョン 1.19.0 の Dart SDK 制約を指定する必要があります。

このページのコンテンツは役立ちましたか？

フィードバックありがとうございます！

詳細を報告する

フィードバックありがとうございます！改善のために何ができるかお知らせください。

詳細を報告する

特に記載がない限り、このサイトのドキュメントは Dart 3.8.1 を反映しています。ページは 2025-05-29 に最終更新されました。ソースを表示または問題を報告。

pubspec ファイル

サポートされているフィールド

例

詳細

名前

バージョン

説明

ホームページ

リポジトリ

Issue tracker

ドキュメント

依存関係

Executables

Platforms

Publish_to

Funding

False_secrets

Screenshots

Topics

Ignored_advisories

SDK constraints

Flutter SDK 制約