
llama.cpp の --mlock で起動しないなら -lm mmap+mlock へ――書き換え4つと、黙って無視される環境変数(llama-server の VmLck で実測)
llama.cpp の公式 Docker イメージ ghcr.io/ggml-org/llama.cpp:server の最新版(2026年9月28日時点の build 11223)で、--mlock を付けて llama-server を起動しました。サーバーは「error: invalid argument: --mlock」の1行だけを出して、すぐに終了しました(終了コード 1)。--no-mmap、--mmap、-dio も同じです。
この記事は、llama-server(llama.cpp の HTTP サーバー)を Docker やスクリプトで動かしていて、イメージや版を上げたら、このエラーで起動しなくなった方に向けたものです。もう1つ、環境変数(LLAMA_ARG_MLOCK など)でメモリの設定をしている方も対象です。こちらはエラーが出ないまま、設定が効かなくなっていました。
原因は、2026年9月9日(build 10875、安定版では v0.4.1)に、旧フラグが削除されたことです。モデルの読み込み方の指定は、7月に追加された --load-mode(短い形は -lm)にまとめられました。ただし、名前が同じ値を選ぶと、意味が変わります。旧 --mlock を -lm mlock に書き換えると、7月23日より前の --mlock とは違う動きになります(同じ動きにするのは -lm mmap+mlock です。--no-mmap と併用していた場合は -lm mlock です)。7月23日から9月9日までの移行期間に出ていた警告も、この名前が同じ値を案内していました。
公式イメージの7つの版(2026年7月23日〜9月28日)で、小さなモデル(144,811,072 バイト)を読み込みました。旧フラグ・環境変数・設定ファイルの書き方ごとに、モデルがメモリにどう置かれたかを、Linux の /proc にある値(VmLck など)で確かめています。確かめたのは CPU 版の Docker イメージだけで、GPU では確かめていません。
すぐに直したい方は、結論を読んでから3章へ進んでください。
結論
当てはまるかを確かめる
旧い名前がどこに残っているかで、症状が違います(最後の項目以外は、9月28日時点の最新版で実測)。
起動の引数(docker run、compose の command、スクリプト): 「error: invalid argument: --mlock」(--no-mmap などはその名前)の1行を出して、終了します
ルーターのプリセットのファイル(--models-preset): 「option 'mlock' not recognized in preset …」を出して、ルーターが起動しません(ルーターは、1つの llama-server で複数のモデルを切り替えて扱うモードです)
設定ファイル(~/.config/llama.cpp/config.ini など): 「ignoring option 'mlock' …」の警告を出して、起動します。設定は効いていません
環境変数(LLAMA_ARG_MLOCK など): 何も出ずに起動します。設定は効いていません
移行期の版(7月27日の変更の後、9月9日の削除までの版)のまま使っている: 非推奨の警告(use --load-mode mlock instead)は出ますが、動きが変わったことは表示されません。--mlock は、すでに mmap せずに固定する動きです(1章。build 10156・10868 で実測)
使っている版は、次のコマンドで確かめます(ご自身のイメージのタグに読み替えてください。:server のように版を固定しないタグは、手元に無いと、その時点の最新版を取得します)。
docker run --rm ghcr.io/ggml-org/llama.cpp:server --versionversion: 0.5.0-dev (build 11223, commit 4da633776)
built with GNU 14.2.0 for Linux x86_64
build の番号が 10875 以上なら、旧フラグは使えません(0.5.0-dev のような版の表記ではなく、build の番号で判断します。削除の直前の版も直後の版も、0.4.0-dev と表示されました。7月ごろの版は、version: 10103 (c588c4f47) のように番号だけが出ます)。Docker イメージのタグ server-b10884 の 10884 も、build の番号です。ヘルプに --mlock があるかでも確かめられます。
docker run --rm ghcr.io/ggml-org/llama.cpp:server --help | grep -E '^(--mlock|-lm)'-lm, --load-mode MODE model loading mode (default: auto)
-lm の行だけなら削除後の版です。--mlock の行に「DEPRECATED」と出れば移行期の版、--mlock の行だけで -lm の行が無ければ、7月23日より前の版です。
古い名前が残っていないかは、設定を置いているディレクトリで次のコマンドを実行すると探せます。旧フラグ、環境変数、設定ファイルのキーを拾います(読み取るだけで、ファイルは書き換えません)。bash で動かすコマンドです(Windows では WSL か Git Bash)。-I で、モデルのようなバイナリのファイルは飛ばします。
grep -rnIE -e '--mlock|--no-mmap|--mmap|-dio|-ndio|--direct-io|--no-direct-io' -e 'LLAMA_ARG_(NO_)?(MLOCK|MMAP|DIO)' -e '^[[:space:]]*(no-)?(mlock|mmap|direct-io|dio)[[:space:]]*=' .検証用に、古い書き方の compose.yaml・プリセットのファイル(models.ini)・起動スクリプト(start.sh)を置いたディレクトリで実行すると、次のように出ました。
./start.sh:2:exec llama-server -m /models/model.gguf --mlock -t 8
./models.ini:4:mmap = 1
./models.ini:8:mlock = true
./compose.yaml:4: command: -m /models/model.gguf --no-mmap
./compose.yaml:6: LLAMA_ARG_MLOCK: "1"
書き換え4つ(7月23日より前と同じ動きにする)
迷ったら、この表のとおりに書き換えます。旧フラグの並べ方(--mlock --no-mmap の順番など)は問いません。
--mlock(環境変数 LLAMA_ARG_MLOCK=1、プリセットのキー mlock = true) → -lm mmap+mlock。-lm mlock ではありません
--no-mmap(LLAMA_ARG_MMAP=0、LLAMA_ARG_NO_MMAP=1、no-mmap = true) → -lm none。移行期の警告が案内していた -lm mmap にすると、逆に mmap を使う設定になります
--no-mmap と --mlock の両方(LLAMA_ARG_MMAP=0 と LLAMA_ARG_MLOCK=1、no-mmap = true と mlock = true) → -lm mlock
-dio(--direct-io)(LLAMA_ARG_DIO=1) → -lm dio
--mmap を付けていた場合と、何も付けていなかった場合は、何も書かなくて構いません。既定の auto は、CPU だけで動かす場合は mmap と同じ動きでした(GPU を使う場合、auto は「mmap に対応しないデバイスがあれば mmap しない」とヘルプにあります。GPU では確かめていません)。
書き換え先の書き方は、次のとおりです(例は3章)。
起動の引数: -lm mmap+mlock のように書きます
環境変数: LLAMA_ARG_LOAD_MODE に、上の値(mmap+mlock など)を入れます
プリセットと設定ファイル: load-mode = mmap+mlock のように書きます
設定ファイル(config.ini。8月12日に追加)の mlock = 1 は、削除の直前の版(build 10868)では mmap せずに固定していました。7月23日より前の --mlock と同じにするなら load-mode = mmap+mlock、削除の直前の動きを保つなら load-mode = mlock です。
やること
上の表のとおりに書き換えます。移行期の警告に従って -lm mlock にした場合は、7月23日より前の --mlock と違い、mmap を使わない動きになっています。前と同じ動きにしたいなら -lm mmap+mlock にします
環境変数で指定していた場合は、エラーが出ていなくても書き換えが必要です。削除後の版は、古い環境変数を何も言わずに無視します(2章)
書き換えたら、実際に固定されたかを VmLck の値で確かめます(3章)
Docker で mlock を使うなら、コンテナに IPC_LOCK の権限を足すか、memlock の上限を外します。足りないと、警告が出るだけで、サーバーは固定しないまま動きます(4章)
1. 何が変わったか
経緯(日付は UTC)
2026年7月23日(PR #20834): --mmap・--no-mmap・--mlock・--direct-io をまとめた --load-mode が追加され、旧フラグは非推奨になりました。この日から9月9日までを、この記事では移行期と呼びます。このときの -lm mlock は「mmap したうえで固定する」という意味でした
2026年7月27日(PR #26135): -lm mlock の意味が「mmap せずに固定する」に変わり、「mmap したうえで固定する」は新しい値の mmap+mlock になりました。非推奨の --mlock も、変わった後の -lm mlock と同じ動きになりました
2026年9月9日(PR #28334、build 10875): 旧フラグと、それに対応する環境変数の定義が削除されました。安定版では v0.4.1(9月14日)から、公式の Docker イメージでは server-b10884(9月10日)からです。公式イメージは1日1回作られるので、削除を含む最初のイメージの番号は 10875 ではなく 10884 です
参考: PR #26135、PR #28334、v0.4.1 のリリースノート
mmap・mlock・dio と、/proc の値
mmap: モデルのファイルをメモリに写像して(ファイルの中身をメモリの一部として見えるようにして)読みます。/proc の値では、ファイルに由来するメモリ(RssFile)として数えられます
mmap しない(none): モデルをプロセスのメモリに読み込みます。ファイルに由来しないメモリ(RssAnon)として数えられます
mlock: 読み込んだモデルを、スワップや圧縮で追い出されないように固定します。固定した量は VmLck に出ます
dio: direct I/O(OS のファイルのキャッシュを通さずに読む方式)でモデルを読み込みます。mmap はしません
VmLck・RssAnon・RssFile は、Linux の /proc/プロセス番号/status に kB 単位で出ます。公式イメージをそのまま起動した場合、コンテナの中の llama-server のプロセス番号は 1 です。ルーター(--models-preset)では、モデルは別の子プロセスに読み込まれるので、1 の値にはモデルが入りません。
移行期の落とし穴
移行期の警告は、次のように案内していました。
DEPRECATED: --mlock is deprecated. use --load-mode mlock instead
DEPRECATED: --mmap and --no-mmap are deprecated. use --load-mode mmap instead
--mlock への案内(-lm mlock)は、7月27日より前は正しいものでした。しかし、7月27日に -lm mlock の意味が変わった後も、警告の文言は変わりませんでした。そのため、次のことが起きていました。
7月27日の変更の後の移行期の版では、--mlock を付けていると、mmap を使わずに固定していました(2章で実測)
変更の前に、警告どおり -lm mlock に書き換えた場合も、変更の後の版に上げた時点で、何も表示されずに mmap を使わない動きに変わりました
--no-mmap への案内(mmap)は、移行期の初めから、同じ動きになる none とは違っていました。--mmap と --no-mmap に、同じ文言の警告が出ていたためです(PR #20834 の差分による)。
mmap したうえで固定するか、しないで固定するかで、固定される量(VmLck)は変わりませんでした。この記事の小さなモデルでは、プロセスが使うメモリの合計(VmRSS、約191,000 kB)も、ほぼ同じでした。変わったのは、モデルがファイルに由来するメモリとして置かれるか、プロセスのメモリに読み込まれるかです。公式のヘルプは mmap について「無効にすると読み込みが遅くなるが、mlock を使わない場合はページアウトが減ることがある」と説明しています。大きなモデルで、読み込みの速さや、メモリが足りないときの振る舞いがどう違うかは測っていません。前と同じ動きを保ちたい場合は、表のとおり mmap+mlock にしてください。
2. 実測: 古い名前はどう扱われるか
公式イメージの CPU 版の server を使いました。build 10103(7月23日、--load-mode の追加前)、10108・10143(追加後、7月27日の変更前)、10156(変更後)、10868(削除前の最後)、10884(削除後の最初)、11223(9月28日の最新)の7つです。
旧フラグは、エラーで止まる
build 10884 と 11223 では、--mlock・--no-mmap・--mmap・-dio のどれも、「error: invalid argument: 〜」の1行を出して、終了コード 1 で終わりました。使い方の案内は出ません。--no-mmap --mlock と並べた場合は、最初の --no-mmap で止まります。-ndio(--no-direct-io)と、llama-bench の -mmp・-dio も、同じ PR で削除されています(PR の差分による。実測はしていません)。
環境変数は、黙って無視される
build 11223 で、次の環境変数を渡して起動しました。どれも、エラーも警告も出ずに起動し、指定は効いていませんでした(VmLck 0、mmap のまま)。
LLAMA_ARG_MLOCK=1
LLAMA_ARG_MMAP=0
LLAMA_ARG_NO_MMAP=1
LLAMA_ARG_DIO=1
build 10103 では、どれも効いていました。7月の時点(build 10103)の llama-server の README は、真偽値の環境変数の例に LLAMA_ARG_MMAP と LLAMA_ARG_NO_MMAP を使っていました(8月15日の PR #26934 で差し替え)。この例をまねて書いた設定も、同じく効かなくなっています。代わりの LLAMA_ARG_LOAD_MODE=mmap+mlock は、build 11223 で効きました。
プリセットの古いキーはルーターを止め、設定ファイルの古いキーは警告して無視される
ルーターのプリセット(--models-preset): mlock = true、no-mmap = true、LLAMA_ARG_MLOCK = 1 のどれかが残っていると、build 11223 のルーターは起動せずに終了しました(終了コード 1)。smol は、検証のプリセットで付けたモデルの名前です
llama_server: failed to initialize router models: option 'mlock' not recognized in preset 'smol'
公式ドキュメント(docs/preset.md)のプリセットの例も、[*] の節に mmap = 1 が残っています(9月28日時点)。例の [*] の節をそのまま使うと、同じエラーで起動しませんでした
llama_server: failed to initialize router models: option 'mmap' not recognized in preset '*'
設定ファイル(すべての llama.cpp の道具に共通の設定ファイル。~/.config/llama.cpp/config.ini と /etc/llama.cpp/config.ini。8月12日に追加): mlock = 1 は、次の警告を出したうえで無視され、サーバーは固定しないまま起動しました
ignoring option 'mlock' from /models/xdg-mlock/llama.cpp/config.ini: not supported by this program
逆に、load-mode = mmap+mlock と書いたプリセットは、build 10103 のルーターでは「option 'load-mode' not recognized」で起動しません。7月23日より前の版と削除後の版の両方で、読み込み方を指定するプリセットは、試したキーでは書けませんでした(移行期の版では、build 10868 が公式ドキュメントの例の mmap = 1 を警告付きで受け付けることだけ確かめました。load-mode のキーは、移行期の版では試していません)。ルーターの版を上げるときは、プリセットも同時に書き換えます。
書き換え4つの裏付け
build 10103 の旧フラグと、build 11223 の -lm の値で、VmLck(固定した量)と、RssAnon・RssFile のどちらにモデルが載るかを比べました。固定すると VmLck は 139,680 kB になります。
旧 --mlock: VmLck 139,680 kB、RssFile 155,812 kB(mmap のまま固定) → -lm mmap+mlock で VmLck 139,680 kB、RssFile 156,180 kB
旧 --no-mmap: VmLck 0、RssAnon 174,116 kB(プロセスのメモリに読み込み) → -lm none で VmLck 0、RssAnon 175,112 kB
旧 --no-mmap --mlock: VmLck 139,680 kB、RssAnon 174,116 kB → -lm mlock で VmLck 139,680 kB、RssAnon 175,116 kB
旧 -dio: VmLck 0、RssAnon 174,180 kB → -lm dio で VmLck 0、RssAnon 175,180 kB
何も付けない: VmLck 0、RssFile 155,868 kB → -lm auto(既定)で RssFile 156,392 kB
環境変数とプリセットのキーも、build 10103 では、それぞれ同じ行の旧フラグと同じ結果でした。-lm mlock+mmap のように語の順番を逆にすると、「error while handling argument "-lm": invalid value」で起動しません。
移行期の版は、7月27日から --mlock の意味が変わり、並べ方で結果が変わった
--mlock だけを付けたときと、-lm mlock の結果です。
build 10108・10143(7月27日の変更前): --mlock も -lm mlock も、mmap のまま固定(RssFile 約155,600〜155,900 kB)。-lm mmap+mlock はまだ無く、「invalid value」で起動しません
build 10156・10868(7月27日の変更後): --mlock も -lm mlock も、mmap せずに固定(RssAnon 約174,100〜175,100 kB)。警告は「use --load-mode mlock instead」のまま
build 10868 では、旧フラグを並べると、最後に書いたものだけが効きました。
--no-mmap --mlock: mmap せずに固定
--mlock --no-mmap: 固定されない(VmLck 0)
--mlock --mmap: mmap だけで、固定されない
build 10103 では、順番に関係なく、両方が効いていました。移行期の版を使っている場合は、旧フラグの順番によっては、すでに固定が外れている可能性があります(順番を確かめたのは build 10868 だけです)。
3. 書き換え方
memlock の上限が足りない環境で Docker で固定するには、IPC_LOCK の権限を足すか、memlock の上限を外すかの、どちらか一方が要ります(4章)。下の docker run の例は前者、compose の例は後者です。
docker run の場合
次のコマンドは、コンテナを起動し、127.0.0.1 の 8080 番ポートを使います。--cap-add IPC_LOCK は、コンテナにメモリの固定を許す権限です。mlock はモデルの大きさの分だけメモリを固定するので、メモリに余裕の無いマシンでは、ほかのプログラムを圧迫することがあります。最初から本番の環境では試さないでください。実行によって生じた損害については、責任を負いかねます。-v のボリューム(llama-models)とモデルのパスは、検証で使ったものです。ご自身の環境のものに読み替えてください。
docker run -d --name llama --cap-add IPC_LOCK -p 127.0.0.1:8080:8080 -v llama-models:/models ghcr.io/ggml-org/llama.cpp:server -m /models/SmolLM2-135M-Instruct-Q8_0.gguf -lm mmap+mlock起動したら、固定されたかを確かめます(読み取るだけです)。
docker exec llama grep -E 'VmLck|RssAnon|RssFile' /proc/1/statusVmLck: 139680 kB
RssAnon: 208984 kB
RssFile: 156200 kB
VmLck を正とします。モデルの大きさに近ければ固定されています。0 なら固定されていません。ログに「failed to mlock」(4章)が出ていたら、VmLck がモデルの大きさより小さくないかを見直します
mmap しているかは RssFile で見ます。モデルの大きさ程度(この例で約156,000 kB)なら mmap、約16,000 kB 程度に小さければ mmap していません。RssAnon には、会話の文脈を置くメモリなども入るので、mmap していても大きくなります。この例の RssAnon(約209,000 kB)が、2章の同じ -lm mmap+mlock(約35,400 kB)より大きいのは、主にコンテキスト長の違いです。-c を指定しないこの例は 8192(ログの n_ctx_slot)、2章は -c 512 でした
Docker を使わずに動かしている場合は、プロセス番号を pidof で探して、同じ値を読みます(Linux の場合。llama-server のプロセスが1つのときの形です。下の出力は、コンテナの中で同じコマンドを実行した例です)。
grep -E 'VmLck|RssAnon|RssFile' /proc/$(pidof llama-server)/statusVmLck: 139680 kB
RssAnon: 209008 kB
RssFile: 156568 kB
compose の場合
環境変数で指定するなら、LLAMA_ARG_LOAD_MODE を使います。次の compose.yaml は、memlock の上限を外す形です(ulimits の memlock: -1)。docker run の例と同じく、コンテナを起動して 127.0.0.1 の 8080 番ポートを使います。volumes の llama-models は、モデルを入れておいた名前付きボリュームです(external: true なので、先に作ってある必要があります)。ご自身のモデルの置き場所に読み替えてください。
services:
llama:
image: ghcr.io/ggml-org/llama.cpp:server
command: -m /models/SmolLM2-135M-Instruct-Q8_0.gguf
environment:
LLAMA_ARG_LOAD_MODE: mmap+mlock
ulimits:
memlock: -1
ports:
- "127.0.0.1:8080:8080"
volumes:
- llama-models:/models
volumes:
llama-models:
external: truedocker compose up -ddocker compose exec llama grep -E 'VmLck|RssAnon|RssFile' /proc/1/statusVmLck: 139680 kB
RssAnon: 208984 kB
RssFile: 156460 kB
プリセットと設定ファイルの場合
プリセットのファイルでは、load-mode のキーで書きます(短い形の lm でも通りました)。
version = 1
[smol]
model = /models/SmolLM2-135M-Instruct-Q8_0.gguf
load-on-startup = true
load-mode = mmap+mlock設定ファイル(config.ini)も、同じ1行で固定できました(build 10868 と 11223)。
load-mode = mmap+mlock4. Docker で mlock を効かせる
Docker は、既定ではコンテナに IPC_LOCK の権限を与えません。そのため、コンテナの中の root でも、固定できる量は memlock の上限(RLIMIT_MEMLOCK)までです。上限が足りないと、llama-server は次の警告を出し、固定しないまま起動を続けます。
memlock の上限を 8MiB(8,388,608 バイト)にしたコンテナで、IPC_LOCK を付けずに -lm mmap+mlock で起動したときのログと、VmLck です。
docker logs llama 2>&1 | grep -A1 'failed to mlock'0.00.176.640 W warning: failed to mlock 31866880-byte buffer (after previously locking 0 bytes): Cannot allocate memory
Try increasing RLIMIT_MEMLOCK ('ulimit -l' as root).
docker exec llama grep -E 'VmLck|RssAnon|RssFile' /proc/1/statusVmLck: 0 kB
RssAnon: 208984 kB
RssFile: 156476 kB
次のどちらかで固定できました。
IPC_LOCK の権限を足す(3章の docker run の形): memlock の上限が 8MiB のままでも固定できました。compose にも同じ意味の cap_add の項目がありますが、compose では確かめていません
memlock の上限を外す(3章の compose の形): docker run では --ulimit オプションで memlock を -1 にして確かめました。--cap-drop ALL で権限をすべて外しても、固定できました。compose の ulimits の memlock がコンテナに届くことは、同じ compose.yaml で値を 8388608 にすると、コンテナの中の上限が 8192 kB になり、固定できなくなることで確かめました
memlock の上限の既定値は、環境によって違います。検証に使った Docker Desktop(Windows、WSL2)では、コンテナの既定は unlimited で、何も付けなくても固定できました。Docker の公式ドキュメントによると、指定しない場合はデーモンの既定を引き継ぎます。Linux のサーバーで動かす Docker Engine の既定値は確かめていないので、ご自身の環境では、3章の VmLck の確かめ方で確認してください。
まとめ
llama.cpp の旧フラグ(--mlock・--no-mmap・--mmap・-dio)は、2026年9月9日の build 10875(安定版 v0.4.1、Docker の server-b10884)で削除されました。渡すと「error: invalid argument」で起動しません
書き換えは、--mlock → -lm mmap+mlock、--no-mmap → -lm none、--no-mmap --mlock → -lm mlock、-dio → -lm dio の4つです。移行期の警告の案内(mlock、mmap)とは違います
環境変数(LLAMA_ARG_MLOCK など)は、エラーも警告も無く無視されます。プリセットの古いキーはルーターを止め、設定ファイルの古いキーは警告して無視されます
Docker で mlock を使うなら、IPC_LOCK か memlock の上限が要ります。足りなくてもサーバーは動くので、VmLck で確かめます
検証の条件と、確かめていないこと
検証日: 2026年9月28日。Windows 11 上の Docker Desktop(Docker Engine 29.8.0、WSL2)
イメージ: ghcr.io/ggml-org/llama.cpp の server-b10103・b10108・b10143・b10156・b10868・b10884・b11223(CPU 版)。build 11223 は、9月28日時点の server タグと同じイメージです
モデル: unsloth/SmolLM2-135M-Instruct-GGUF の Q8_0(144,811,072 バイト)。コンテナの中でダウンロードし、名前付きボリュームに置きました
2章の測定は、ネットワークを外したコンテナで、CPU 2つ・2スレッド・コンテキスト長 512 に絞って動かし、起動を待ってから /proc/1/status を読みました(ルーターは、モデルを読み込んだ子プロセスの値)。推論はしていません。3章・4章のコマンドは、記事に載せた形のまま実行しました(4章の上限は --ulimit memlock=8388608:8388608 で付けました)
確かめていないことは、次のとおりです。
GPU の版(CUDA・Vulkan など)と、GPU に載せた場合。既定の auto が mmap 以外になる条件
llama-cli・llama-bench など、llama-server 以外の道具
大きなモデル、メモリが足りない状況、読み込みや推論の速さ
Linux の Docker Engine での、memlock の既定の上限
移行期の版のうち、測ったのは build 10108・10143・10156・10868 の4つ(順番の実測は 10868 だけ)