Lock file#

PDMは、pdm.lockという名前の既存のロックファイルからパッケージを排他的にインストールします。このファイルは、依存関係をインストールするための唯一の情報源として機能します。ロックファイルには、次のような重要な情報が含まれています。:

すべてのパッケージとそのバージョン
パッケージのファイル名とハッシュ
オプションで、パッケージをダウンロードする元のURL(Static URLsも参照)
各パッケージの依存関係とマーカー(Inherit the metadata from parentsも参照)

update strategiesをpdm addとして追加します。さらに、pdm installおよびpdm addコマンドを使用すると、自動的にpdm.lockファイルが作成されます。

Should I add pdm.lock to version control?

場合によります。CIでローカル開発と同じ依存関係バージョンを使用し、予期しない失敗を回避することが目的の場合は、pdm.lockファイルをバージョン管理に追加する必要があります。そうでない場合、プロジェクトがライブラリであり、CIでユーザーサイトのインストールを模倣して、PyPIの現在のバージョンで何も壊れないようにしたい場合は、pdm.lockファイルをサブミットしないでください。

Install the packages pinned in lock file#

このジョブを実行するための類似したコマンドがいくつかありますが、若干の違いがあります。:

pdm syncはロックファイルからパッケージをインストールします。
pdm updateはロックファイルを更新し、次にpdm syncを更新します。
pdm installは、プロジェクトファイルの変更をチェックし、必要に応じてロックファイルを更新してからpdm syncを実行します。

pdm syncには、インストールされたパッケージを管理するためのオプションもいくつかあります。:

--clean:ロックファイルに存在しないパッケージを削除します。
--clean-unselected(または--only-keep):--cleanのより完全なバージョンで、--G、--d、--prodオプションで指定されたグループにないパッケージも削除します。注:デフォルトでは、pdm syncはロックファイルからすべてのグループを選択するので、--clean-unselectedは--cleanと同じです。ただし、--G、--d、--prodが使用されている場合は除きます。

Hashes in the lock file#

デフォルトでは、pdm installはロックファイルがpyproject.tomlの内容と一致するかどうかをチェックします。これは、ロックファイルにpyproject.tomlの内容ハッシュを保存することによって行われます。

ロック・ファイル内のハッシュが最新かどうかを確認するには、次のようにします。

1	`pdm lock --check`

依存関係を変更せずにロックファイルを更新したい場合は、--refreshオプションを使用できます。:

1	`pdm lock --refresh`

このコマンドは、ロックファイルに記録されているすべてのファイルハッシュも更新します。

Specify another lock file to use#

デフォルトでは、PDMはカレントディレクトリのpdm.lockを使用します。-L/--lockfileオプションまたはPDM_LOCKFILE環境変数を使用して別のロックファイルを指定できます。

pdm install --lockfile my-lockfile.lock

このコマンドは、パッケージをpdm.lockではなくmy-lockfile.lockからインストールします。

代替ロックファイルは、異なる環境に競合する依存関係が存在する場合に役立ちます。この場合、それらをまとめてロックすると、PDMでエラーが発生します。そのため、select a subset of dependency groupsを実行し、別々にロックする必要があります。

現実的な例として、プロジェクトがwerkzeugのリリースバージョンに依存しており、開発時にローカルの開発中のコピーを使用したい場合があります。pyproject.tomlに次のものを追加できます。

[project]
requires-python = ">=3.7"
dependencies = ["werkzeug"]

[tool.pdm.dev-dependencies]
dev = ["werkzeug @ file:///${PROJECT_ROOT}/dev/werkzeug"]

次に、さまざまなオプションを指定してpdm lockを実行し、さまざまな目的のロックファイルを生成します。:

# Lock default + dev, write to pdm.lock
# with the local copy of werkzeug pinned.
pdm lock
# Lock default, write to pdm.prod.lock
# with the release version of werkzeug pinned.
pdm lock --prod -L pdm.prod.lock

ロックファイルのmetadata.groupsフィールドをチェックして、どのグループが含まれているかを確認します。

Option to not write lock file#

ロックファイルを更新せずに依存関係を追加または更新したい場合や、pdm.lockを生成したくない場合は、--frozen-lockfileオプションを使用できます。

pdm add --frozen-lockfile flask

この場合、ロック・ファイル(存在する場合)は読取り専用になり、書込み操作は実行されません。ただし、必要に応じて依存関係の解決手順は実行されます。

Lock strategies#

現在、ロック動作を制御する3つのフラグcross_platform、static_urlsおよびdirect_minimal_versionsがサポートされています。その意味は次のとおりです。--strategy/-Sオプションを使用して、1つ以上のフラグをpdm lockに渡すことができます。これは、コンマ区切りのリストを指定するか、オプションを複数回渡すことによって行います。これらのコマンドはどちらも同じように機能します。:

pdm lock -S cross_platform,static_urls
pdm lock -S cross_platform -S static_urls

フラグはロックファイルにエンコードされ、次にpdm lockを実行したときに読み込まれます。ただし、フラグ名の前にno_を付けることでフラグを無効にすることができます。

pdm lock -S no_cross_platform

このコマンドは、ロックファイルをクロスプラットフォームにしません。

Cross platform#

Added in version 2.6.0

Deprecated in 2.17.0

新しい動作については、Lock for specific platforms or Python versionsを参照してください。

デフォルトでは、生成されたロックファイルはcross-platformです。これは、依存関係を解決するときに現在のプラットフォームが考慮されないことを意味します。結果のロックファイルには、すべての可能なプラットフォームとPythonバージョンのホイールと依存関係が含まれます。ただし、リリースにすべてのホイールが含まれていない場合、誤ったロックファイルが作成されることがあります。これを回避するには、現在のプラットフォームに関係のないホイールをトリミングして、このプラットフォームのみで動作するロックファイルを作成するようPDMに指示します。これは、--strategy no_cross_platformオプションをpdm lockに渡すことで実行できます。

pdm lock --strategy no_cross_platform

Static URLs#

Added in version 2.8.0

デフォルトでは、PDMはパッケージのファイル名のみをロックファイルに保存するため、異なるパッケージインデックス間での再利用性が向上します。ただし、パッケージの静的URLをロックファイルに保存する場合は、--strategy static_URLsオプションをpdm lockに渡すことができます。

pdm lock --strategy static_urls

設定は同じロックファイルに保存され、記憶されます。--strategy no_static_urlsを渡して無効にすることもできます。

Direct minimal versions#

Added in version 2.10.0

--strategy direct_minimal_versionsを渡して有効にすると、pyproject.tomlで指定された依存関係は、最新バージョンではなく、利用可能な最小バージョンに解決されます。これは、ある範囲の依存関係バージョン内でプロジェクトの互換性をテストしたい場合に便利です。

例えば、pyproject.tomlでflask>=2.0を指定した場合、他に互換性の問題がなければflaskはバージョン2.0.0に解決されます。

Note

パッケージの依存関係のバージョン制約は、将来にわたって有効ではありません。最小バージョンへの依存関係を解決すると、下位互換性の問題が発生する可能性があります。たとえば、flask==2.0.0にはwerkzeug>=2.0が必要ですが、実際には2年後にリリースされたWerkzeug 3.0.0では動作しません。

Inherit the metadata from parents#

Added in version 2.11.0

inherit_metadataストラテジーを有効にすると、PDMはパッケージの祖先から環境マーカーを継承してマージします。これらのマーカーはロック中にロックファイルにエンコードされるため、インストールが高速化されます。これはバージョン2.11.0からデフォルトで有効になっています。構成でこのストラテジーを無効にするには、pdm config strategy.inherit_metadata falseを使用します。

Exclude packages newer than specific date#

Added in version 2.13.0

--exclude-newerオプションをpdm lockに渡すことで、指定された日付より新しいパッケージを除外できます。これは、たとえばビルドの再現性を確保するために、依存関係を特定の日付にロックしたい場合に便利です。

日付はRFC 3339タイムスタンプ(例:2006-12-02T02:07:43Z)または同じ形式のUTC日付(例:2006-12-02)で指定できます。

pdm lock --exclude-newer 2024-01-01

Note

パッケージインデックスは、PEP 700で規定されているように、upload-timeフィールドをサポートしていなければなりません。フィールドが与えられた配布に存在しない場合、その配布は利用できないものとして扱われます。

Set acceptable format for locking or installing#

パッケージのフォーマット(binary/sdist)を制御する場合は、環境変数PDM_NO_BINARY、PDM_ONLY_BINARYおよびPDM_PREFER_BINARYを設定できます。

各env変数は、パッケージ名のコンマ区切りのリストです。すべてのパッケージに適用するには、これを:all:に設定します。例:

# No binary for werkzeug will be locked nor used for installation
PDM_NO_BINARY=werkzeug pdm add flask
# Only binaries will be locked in the lock file
PDM_ONLY_BINARY=:all: pdm lock
# No binaries will be used for installation
PDM_NO_BINARY=:all: pdm install
# Prefer binary distributions and even if sdist with higher version is available
PDM_PREFER_BINARY=flask pdm install

これらの値は、tool.pdm.resolutionセクションのno-binary、only-binary、prefer-binaryキーを使用して、プロジェクトpyproject.tomlで定義することもできます。これらは環境変数と同じ形式を受け入れ、リストもサポートします。

[tool.pdm.resolution]
# No binary for werkzeug and flask will be locked nor used for installation
no-binary = "werkzeug,flask"
# equivalent to
no-binary = ["werkzeug", "flask"]
# Only binaries will be locked in the lock file
only-binary = ":all:"
# Prefer binary distributions and even if sdist with higher version is available
prefer-binary = "flask"

Note

それぞれの環境変数はpyproject.tomlよりも優先されます。

Allow prerelease versions to be installed#

有効にするには、pyproject.tomlに次の設定を含めます。:

[tool.pdm.resolution]
allow-prereleases = true

Solve the locking failure#

PDMが要件を満たす分解能を見つけられない場合は、エラーが発生します。たとえば

pdm django==3.1.4 "asgiref<3"
...
🔒 Lock failed
Unable to find a resolution for asgiref because of the following conflicts:
    asgiref<3 (from project)
    asgiref<4,>=3.2.10 (from <Candidate django 3.1.4 from https://pypi.org/simple/django/>)
To fix this, you could loosen the dependency version constraints in pyproject.toml. If that is not possible, you could also override the resolved version in `[tool.pdm.resolution.overrides]` table.

djangoの下位バージョンに変更するか、asgirefの上限を削除することができます。しかし、プロジェクトに適さない場合は、pyproject.tomlで解決されたパッケージのバージョンを上書きする、またはその特定のパッケージをロックしないを試してみてください。

Export locked packages to alternative formats#

pdm.lockファイルを他のフォーマットにエクスポートして、CIフローまたはイメージ構築プロセスを簡略化できます。現在サポートされているのはrequirements.txtフォーマットのみです。

pdm export -o requirements.txt

Tip

.pre-commit hookを使用してpdm exportを実行することもできます。