追加の Python ライブラリ：~/.xefm/requirements.txt

English | 日本語

config.py でできることの中には、XeFM に同梱されていない Python ライブラリを必要とするものがあります。pillow-heif のような Pillow プラグイン、IMAGE_DECODERS のエントリでカメラの RAW を扱うための rawpy、自分のアクションが import するものなどです。それらを config.py と同じ場所にある ~/.xefm/requirements.txt に書き、同期します。

# ~/.xefm/requirements.txt
pillow-heif
rawpy

xefm deps sync

XeFM の中からなら Tools → Advanced → Sync Python Packages です（コマンドパレットでは sync_python_packages）。同期はバックグラウンドで実行され、pip の出力はログペインに表示され、終わると設定が再読み込みされます。

これはどのインストール方法でも同じように動きます。macOS アプリ（DMG または Homebrew cask）、Windows アプリ（zip または Microsoft Store）、Homebrew formula、pipx / uv / pip のいずれもです。ライブラリは XeFM 自体のインストール先ではなく ~/.xefm/site-packages/ に置かれるので、XeFM をアップグレードしても残ります。

動作の仕組み

• 基準はファイルです。 行を削除して同期すると、そのライブラリは削除されます。空のファイル（またはファイルがないこと）は、すべてを削除するという意味になります。
• XeFM 自身のライブラリが優先されます。 書いたライブラリが、XeFM がすでに使っているもの（Pillow、Pygments など）の別のバージョンを必要とする場合、同期は失敗し、ログに衝突している両方の名前が表示されます。同期が成功するまでは何も変わりません。
• 知らないうちに何かがダウンロードされることはありません。 起動時に XeFM がするのは、前回の同期以降にファイルが変更されたか、XeFM 自体がアップグレードされたかをオフラインで確認することだけです。そうであれば、同期が必要だとログに表示されます。同期は常に自分で始めるものです。
• Python の新しいバージョンでは同期が 1 回必要です。 ライブラリは Python のバージョンごとに保持されます（site-packages/3.14/）。新しい XeFM がより新しい Python で動くと、ログにその旨が表示され、同期すると同じ一覧が改めてインストールされます。
• 読み込み済みのライブラリは再起動で更新されます。 すでに import されたライブラリは、XeFM を再起動するまで古いバージョンのままです。Windows では、使用中のライブラリを置き換えられない場合、次回の起動時に新しい一式に切り替わります。

ライブラリを必要とする拡張機能

拡張パッケージは、必要なライブラリをマニフェスト（requires.python_packages）に書いておけます。同じ同期で、それらも requirements.txt と一緒にインストールされ、すべてまとめて依存関係が解決されます。そうした拡張機能をインストールすると、すぐに同期するかどうかを尋ねられます。同期が実行されるまで拡張機能は読み込まれず、ログにその理由が表示されます。拡張機能を削除または無効にしても、そのライブラリは次の同期まで残ります。

コマンド

requirements.txt は普通の pip の requirements ファイルです。バージョン指定、--index-url、~/.xefm からの相対パスがすべて使えます。ファイルが -r で別のファイルを取り込んでいる場合、その別のファイルを編集しても起動時の確認では気づかれないので、自分で同期を実行してください。

~/.xefm/site-packages/ を手で編集しないでください。同期のたびに置き換えられます。~/.xefm を dotfiles リポジトリで管理している場合は、requirements.txt をコミットし、site-packages/ は含めないでください。各マシンがそれぞれ同期します。