結論

EPERM: operation not permitted は「その操作は、所有者か特権を持つユーザーにしか許されていない」という意味です。Linux・Mac では、他人のファイルへの chmod、スティッキービットのフォルダーでの削除、変更不可の属性が主な原因です。Windows では「アクセスが拒否されました」が EPERM に置き換わって表示されるため、使用中のファイルや管理者権限が原因になることが多くなります。

この記事でわかること

  • EPERM になる16の操作を実際に失敗させたエラー原文と、直したあとの出力
  • npm の EPERM rename・npm cache の EPERM の見え方と直し方
  • EACCES・EBUSY・EROFS との違いと、どこから確かめるかの判断表

2026年11月5日更新|Node.js 22.23.4・npm 10.9.9(Ubuntu 24.04)で実行確認

この記事で実際に動かしたもの:Node.js 22.23.4 と npm 10.9.9 で、権限の無い一般ユーザー(nobody)と root の両方から EPERM になる操作を1つずつ実行し、エラーの原文、strace で見たシステムコール、直したあとの出力を記録しました。

flowchart TD
    E[EPERM が出た] --> A[Windows なら<br>使用中・管理者・開発者モード]
    A -->|Linux・Mac| B[chmod・chown なら<br>所有者を確かめる]
    B -->|違う| C[unlink・rename なら<br>スティッキーと属性]
    C -->|違う| D[kill・setuid なら<br>相手のユーザー]

やりたいことごとに、いちばん早い方法を先にまとめます。

やりたいこと いちばん早い方法 詳しい節
EPERM の意味を知りたい 「所有者か特権が要る操作」。syscall の欄で操作を見る エラー文の読み方
npm install で EPERM(Windows) エディター・開発サーバーを止め、node_modules を消して入れ直す Windows の EPERM
EPERM: operation not permitted, rename ファイルを開いているプログラムを閉じる。Linux は lsattr で属性を見る npm の EPERM rename
npm cache で EPERM npm cache verify。直らなければキャッシュの所有者と属性を見る npm cache の EPERM
chmod・chown で EPERM ls -l で所有者を見て、所有者か sudo で実行する 他人のファイル
sudo でも EPERM になる lsattr で i・a の属性を確かめ、chattr -i で外す 変更不可の属性
symlink で EPERM(Windows) 開発者モードを有効にするか、管理者のターミナルで実行 symlink の EPERM
EACCES との違いを知りたい EACCES は読み書きの許可、EPERM は所有者・特権の問題 違いの表

確認環境:Ubuntu 24.04.5 LTS(Linux カーネル 6.18、ext4)の上で、Node.js 22.23.4 と npm 10.9.9 を使いました。権限の再現は作業用のフォルダーの中だけで行い、権限の無いユーザーは setpriv で nobody(uid 65534)に切り替えて実行しました。変更不可の属性は chattr 1.47、システムコールは strace 6.8 で確かめ、マウント中・読み取り専用の再現は unshare で作った専用のマウント名前空間の中だけで行っています(ホストのファイルとマウントは変えていません)。npm のパッケージはローカルの tgz だけを使い、レジストリには接続していません。出力に出るパスは、読みやすさのため作業用のフォルダーを /work に置き換えています。Windows・Mac の挙動は手元で動かせないため、Node.js 公式ドキュメント(v22 の errors・fs)、libuv のソース(Windows のエラー番号の対応表)、Microsoft Learn(システム エラー コード・シンボリックリンクの作成・開発者モード・Microsoft Defender の除外)、Apple(unlink のマニュアル・ファイルとフォルダへのアクセス)で確かめた範囲だけを書いています。図は mermaid で描画を確かめています(確認日 2026年11月5日)。

本記事の内容は、ご自由にお使いください。
ご利用の際は、出典として本ページへのリンクを記載いただけますようお願いします。

(記載例)出典:株式会社RJC「EPERM: operation not permittedの直し方|npm」

EPERM: operation not permittedとは(エラー文の読み方)

この節では、EPERM が何を意味し、エラー文のどこを見れば原因に近づけるのかが分かります。

EPERM は POSIX で決まっている OS のエラー名で、メッセージは Operation not permitted(操作が許可されていない)、Linux では番号 1 です。Node.js 公式ドキュメントの「よくあるシステムエラー」では、次のように説明されています。

EPERM (Operation not permitted): An attempt was made to perform an operation that requires elevated privileges.

「高い特権が要る操作をしようとした」という説明です。読み書きの許可(rwx)が足りないときの EACCES とは別のエラーで、「ファイルの持ち主か root でなければできない操作」で出ます。権限の無いユーザーで、他人のファイルの権限を変えようとしたときの原文は次のとおりです。

$ node -e "require('fs').chmodSync('/work/own/rootfile.txt', 0o600)"
node:fs:2058
  binding.chmod(path, mode);
          ^

Error: EPERM: operation not permitted, chmod '/work/own/rootfile.txt'
    at Object.chmodSync (node:fs:2058:11)
    at [eval]:1:15
    ...
  errno: -1,
  code: 'EPERM',
  syscall: 'chmod',
  path: '/work/own/rootfile.txt'
}

Node.js v22.23.4

見る場所は4つです。

1syscall:何をしようとしたか

chmod・chown・utime は「持ち主か root だけができる操作」。unlink・rename は削除と名前の変更。open なら書き込み。kill・setuid はプロセスの操作。

2path:対象のファイル

ls -l で持ち主(3列目)を見る。自分でなければ、所有者の問題。自分のものなら、フォルダーのスティッキービットか属性を疑う。

3実行したユーザー

id で今のユーザーを確かめる。root で実行しても EPERM なら、権限ではなく変更不可の属性やマウントの設定が原因。

4errno:-1

OS のエラー番号 1 に負の符号が付いたもの。EACCES は -13、EBUSY は -16。番号が違えば別の原因として調べる。

同じ EPERM でも、syscall の欄は操作によって変わります。手元で操作ごとに起こしたときのメッセージを並べました(nobody で実行。変更不可の属性だけは root で実行)。

操作(Node.js の関数) エラー文(原文) 条件
chmodSyncEPERM: operation not permitted, chmod他人のファイル
chownSyncEPERM: operation not permitted, chown一般ユーザー
utimesSync(時刻を指定)EPERM: operation not permitted, utime他人のファイル
linkSync(ハードリンク)EPERM: operation not permitted, link他人の読み取り専用ファイル
unlinkSyncEPERM: operation not permitted, unlinkスティッキーのフォルダー
renameSyncEPERM: operation not permitted, renameスティッキーのフォルダー
writeFileSyncEPERM: operation not permitted, open変更不可の属性(root でも)
process.killkill EPERM他人のプロセス
process.setuid(0)EPERM, Operation not permitted一般ユーザー

自分で確かめる:OS が返した値を見る

Linux では、strace で Node.js が OS に何を頼み、何が返ったかを1行で見られます。手元の結果です。

strace -e trace=chmod,fchmodat node -e "try{require('fs').chmodSync('/work/own/rootfile.txt',0o600)}catch(e){}" 2>&1 | grep rootfile
chmod("/work/own/rootfile.txt", 0600) = -1 EPERM (Operation not permitted)

シェルの chmod・rm・mv でも、同じ条件なら Operation not permitted と出ます。Node.js 固有のエラーではなく、OS が断った結果を Node.js がそのまま伝えていることが分かります。

16操作EPERM を再現した操作fs・プロセス・npm の3系統
3件表示が EPERM でなかった例OS は EPERM、表示は ENOTDIR・EEXIST
603msリトライ3回で待った時間変更不可の属性では直らない

EPERMの原因一覧(症状→原因→直し方)

この節では、EPERM の主な原因と直し方を、表1枚で見渡せます。

EPERM の原因は「持ち主でない」「特別な属性やフォルダーの設定」「Windows の拒否」の3つに分かれます。手元で再現できたものは「再現」、Windows・Mac の公式ドキュメントで確かめたものは「公式」と書いています。

症状(syscall) 原因 直し方 確かめ方
chmod・chown・utimeファイルの持ち主でない持ち主か sudo で実行。持ち主を直す再現
unlink・rename(他人のファイル)フォルダーにスティッキービット持ち主が消す。自分のフォルダーを使う再現
sudo でも open・unlink・rename変更不可(i)・追記のみ(a)の属性lsattr で確かめ chattr -i・-a再現
npm install の renamenode_modules の中が置き換えられない原因を外し node_modules を作り直す再現
npm cache の rmdir・mkdirキャッシュに消せないファイル属性・持ち主を直す。別のキャッシュ再現
link(ハードリンク)他人のファイルへのリンクを保護コピーかシンボリックリンクにする再現
kill・setuid他人のプロセス・特権が要るそのユーザーか root で実行再現
Windows の rename・unlink・openアクセス拒否(使用中・読み取り専用)使っているプログラムを閉じる公式
Windows の symlinkシンボリックリンク作成の特権が無い開発者モードか管理者で実行公式
Mac の unlink(フォルダー)フォルダーを unlink したrmdir か fs.rm を使う公式

どの原因でも、最初の手がかりは syscall と path の2行です。次の節から、原因ごとに再現した原文と、直したあとの出力を見ていきます。

原因1:他人のファイルへのchmod・chown・utimes(所有者でない)

この節では、読み書きはできるのに chmod・chown で EPERM になる理由と、直し方が分かります。

ファイルの権限(モード)を変えられるのは、そのファイルの持ち主か root だけです。Linux の chmod(2) のマニュアルには、EPERM の条件が次のように書かれています。

The effective UID does not match the owner of the file, and the process is not privileged (Linux: it does not have the CAP_FOWNER capability).

手元では、nobody が持ち主のフォルダーの中に、root が持ち主のファイル(rw-r--r--)を置いて試しました。nobody からは、同じファイルに対する操作でもエラーの種類が分かれました。

# 実行ユーザー uid=65534
[EPERM] chmod 他人のファイル
       EPERM: operation not permitted, chmod '/work/own/rootfile.txt'  (errno -1, syscall chmod)
[EPERM] chown 他人のファイル
       EPERM: operation not permitted, chown '/work/own/rootfile.txt'  (errno -1, syscall chown)
[EPERM] utimes 他人のファイル(時刻を指定)
       EPERM: operation not permitted, utime '/work/own/rootfile.txt'  (errno -1, syscall utime)
[EACCES] 書き込み 他人のファイル(644)
       EACCES: permission denied, open '/work/own/rootfile.txt'  (errno -13, syscall open)

書き込みは「rw-r--r-- の others に w が無い」ので EACCES、権限や持ち主・時刻の変更は「持ち主でない」ので EPERM です。同じファイルでも、操作によって EACCES と EPERM が分かれる点が、見分けの鍵になります。

直し方:持ち主を直してから実行する

多いのは、sudo で作ったファイルやフォルダーが root の持ち物になり、あとから一般ユーザーで chmod しようとする場合です。持ち主を一般ユーザーに戻すと、同じ chmod が通りました。

ls -l /work/own/rootfile.txt
sudo chown "$(id -un)":"$(id -gn)" /work/own/rootfile.txt
node -e "require('fs').chmodSync('/work/own/rootfile.txt', 0o600); console.log('chmod OK')"
-rw-r--r-- 1 root root 10 Nov  5 19:44 /work/own/rootfile.txt
chmod OK
-rw------- 1 nobody nogroup 10 Nov  5 19:44 /work/own/rootfile.txt

chown の使い方は関連記事「chownコマンドの使い方|所有者の変更とchgrp・-Rオプション一覧」で扱っています。755・644 などの数字の意味は関連記事「chmodの755と644の意味|用途別パーミッション早見表」で扱っています。

chmod で EPERM が出たとき

やってはいけないsudo chmod -R 777 でフォルダーごと全員に開ける。持ち主は root のまま残り、ほかの人も書き換えられる
→
代わりにls -l で持ち主を見て、作業するユーザーに chown で戻す。権限は必要な分だけ chmod

見分ける問い:「このファイルの持ち主は、本来だれであるべきか」

ライブラリが chmod・utimes を呼んでいる場合

自分のコードに chmod が無くても、ファイルのコピーや展開をするライブラリが、元の権限や時刻を保とうとして chmod・utimes を呼ぶことがあります。syscall が chmod・utime なのに心当たりが無ければ、コピー先の既存ファイルが他人の持ち物でないかを確かめます。共有フォルダーやマウントしたドライブで起きやすい形です。

原因2:スティッキービットのフォルダーで他人のファイルをrename・削除

この節では、書き込み可能なファイルなのに削除や rename で EPERM になる仕組みと、直し方が分かります。

ファイルを消せるかどうかは、ファイルではなく「入っているフォルダー」の権限で決まります。ただし、フォルダーにスティッキービット(ls -l の末尾が t)が付いていると、他人のファイルは消せず、名前も変えられません。/tmp がこの設定の代表例です。

手元では、drwxrwxrwt(全員が書き込めるスティッキーのフォルダー)に root のファイルを置き、ファイル自体は rw-rw-rw- にして nobody から試しました。

[EPERM] unlink スティッキーの他人のファイル(666)
       EPERM: operation not permitted, unlink '/work/sticky/shared.txt'  (errno -1, syscall unlink)
[EPERM] rename スティッキーの他人のファイル
       EPERM: operation not permitted, rename '/work/sticky/shared.txt' -> '/work/sticky/shared2.txt'  (errno -1, syscall rename)
[OK]   書き込み スティッキーの他人のファイル(666)

中身の書き込みはできるのに、消す・名前を変えることはできません。シェルでも同じでした。

rm: cannot remove '/work/sticky/shared.txt': Operation not permitted
mv: cannot move '/work/sticky/shared.txt' to '/work/sticky/x.txt': Operation not permitted
chmod: changing permissions of '/work/sticky/shared.txt': Operation not permitted
drwxrwxrwt 2 root root 4096 Nov  5 19:44 /work/sticky

Linux の unlink(2) のマニュアルは、この場合を「EPERM or EACCES」と書いています。手元の Linux 6.18 では EPERM でした。Apple の unlink(2) のマニュアルにも、スティッキーのフォルダーで持ち主でないファイルを消そうとすると EPERM になると書かれています。

ふつうのフォルダー(drwxrwxrwx)

フォルダーに書ければ、他人のファイルも消せる

ファイルの rwx は削除に関係しない

rw-r--r-- のファイルも、フォルダーが自分のものなら消せた

スティッキーのフォルダー(drwxrwxrwt)

消せるのはファイルかフォルダーの持ち主と root

他人のファイルは rw-rw-rw- でも消せない

unlink・rename が EPERM になる

直し方:自分のファイルは自分のフォルダーに置く

同じスティッキーのフォルダーでも、自分が作ったファイルなら rename も削除も通りました。

$ echo mine > /work/sticky/mine.txt
$ node -e "const fs=require('fs');fs.renameSync('/work/sticky/mine.txt','/work/sticky/mine2.txt');fs.unlinkSync('/work/sticky/mine2.txt');console.log('rename/unlink OK')"
rename/unlink OK

/tmp に固定の名前(例:/tmp/build.lock)でファイルを作るスクリプトは、別のユーザーが同じ名前で先に作っていると、片付けの段階で EPERM になります。一時ファイルは fs.mkdtempSync(path.join(os.tmpdir(), 'app-')) のように、毎回新しい自分のフォルダーを作ってその中に置くと、この衝突が起きません。

原因3:変更不可の属性(chattr +i・+a)はsudoでもEPERM

この節では、root で実行しても EPERM になる場合の原因と、確かめ方・外し方が分かります。

sudo を付けても EPERM が消えないなら、権限(rwx)ではなくファイルの属性を疑います。Linux の ext4 などには、i(変更不可)と a(追記のみ)の属性があり、付いていると root でも書き換え・削除・名前の変更ができません。unlink(2) のマニュアルにも「The file to be unlinked is marked immutable or append-only.」が EPERM の条件として載っています。

root で実行した原文です。

# 実行ユーザー uid=0
[EPERM] 書き込み immutable
       EPERM: operation not permitted, open '/work/imm/config.json'  (errno -1, syscall open)
[EPERM] unlink immutable
       EPERM: operation not permitted, unlink '/work/imm/config.json'  (errno -1, syscall unlink)
[EPERM] rename immutable
       EPERM: operation not permitted, rename '/work/imm/config.json' -> '/work/imm/c2.json'  (errno -1, syscall rename)
[EPERM] chmod immutable
       EPERM: operation not permitted, chmod '/work/imm/config.json'  (errno -1, syscall chmod)
[OK]   追記 append-only
[EPERM] 上書き append-only
       EPERM: operation not permitted, open '/work/imm/app.log'  (errno -1, syscall open)

追記のみ(a)のファイルは、appendFileSync は通り、writeFileSync(中身を空にしてから書く)は EPERM でした。ログを守るための設定なので、追記はできて上書きはできない、という動きです。

なお、同じファイルを nobody で操作すると、unlink・rename は EACCES になりました。nobody はそもそも入っているフォルダー(root の drwxr-xr-x)に書けないため、属性を調べる前のフォルダーの権限の確認で断られるからです。表示されるのは「最初に引っかかった理由」だけなので、EACCES を直したら次に EPERM が出る、ということも起こります。

確かめ方と外し方

1

lsattr で属性を見る

lsattr ファイル名 で、左から5文字目に i、6文字目に a が出ていれば属性が原因。フォルダー自体は lsattr -d で見る。

----i---------e------- config.json

2

付けた理由を確かめる

設定ファイルを守るために管理者が付けていることがある。自分で付けた覚えが無ければ、管理者に確かめてから外す。

勝手に外さない

3

sudo chattr -i(または -a)で外す

属性の変更には root(CAP_LINUX_IMMUTABLE)が要る。外したあとは、通常の権限の範囲で書き換え・削除ができる。

外したあと元の操作をやり直す

$ lsattr /work/imm
-----a--------e------- /work/imm/app.log
----i---------e------- /work/imm/config.json
$ sudo chattr -i /work/imm/config.json
$ sudo chattr -a /work/imm/app.log
$ node -e "require('fs').writeFileSync('/work/imm/config.json','{}');console.log('書き込み OK')"
書き込み OK

属性は ls -l には表示されません。rwx が正しく見えるのに EPERM が続くときほど、lsattr を1回打つ価値があります。

npmのEPERM rename:node_modulesを置き換えられない

この節では、npm install の「EPERM: operation not permitted, rename」が何をしようとして失敗したのかと、直し方が分かります。

npm は、パッケージを入れ替えるときに、今ある node_modules/パッケージ名 のフォルダーを一時的な名前に rename してから、新しい版を置きます。この rename が断られると EPERM rename になります。Windows ではファイルを開いているプログラムがあると起きやすく、Linux では変更不可の属性で同じ状況を作れます。

手元では、ローカルの tgz で lib-a 1.0.0 を入れ、node_modules/lib-a のフォルダーに変更不可の属性を付けてから、1.0.1 に上げる npm install を root で実行しました。

$ npm install
npm error code ENOTDIR
npm error syscall scandir
npm error path /work/app/node_modules/lib-a/index.js
npm error errno -20
npm error ENOTDIR: not a directory, scandir '/work/app/node_modules/lib-a/index.js'
npm error A complete log of this run can be found in: /work/logs/2026-11-05T10_43_25_734Z-debug-0.log
$ echo $?
236
$ node -e "console.log(require('lib-a'))"
v1.0.0

表示は ENOTDIR でしたが、strace で OS とのやりとりを見ると、実際に断られていたのは EPERM の rename でした。

rename("/work/app/node_modules/lib-a", "/work/app/node_modules/.lib-a-JiD3al2I") = -1 EPERM (Operation not permitted)
rename("/work/app/node_modules/lib-a/index.js", "/work/app/node_modules/.lib-a-JiD3al2I/index.js") = -1 EPERM (Operation not permitted)
rmdir("/work/app/node_modules/lib-a") = -1 EPERM (Operation not permitted)
unlink("/work/app/node_modules/lib-a/index.js") = -1 EPERM (Operation not permitted)
rmdir("/work/app/node_modules/lib-a/index.js") = -1 EPERM (Operation not permitted)

フォルダーの rename が断られたあと、npm 10.9.9 はファイルを1つずつ移す・消す方法に切り替え、それも断られ、最後に「ファイルをフォルダーとして開こうとした」エラー(ENOTDIR)を表示しました。npm や fs.rm が表示するエラー名は、OS が最初に返したものと違うことがあるので、原因が分からないときは strace(Linux)や debug-0.log の verbose stack を見ます。

属性ではなくファイルの中だけが変更不可のとき

フォルダーではなく node_modules/lib-a/index.js だけに属性を付けた場合、npm install は終了コード 0 で終わり、新しい版も入りました。ただし、次の警告が出て、一時的な名前のフォルダーが node_modules に残りました。

npm warn cleanup Failed to remove some directories [
npm warn cleanup   [
npm warn cleanup     '/work/app/node_modules/.lib-a-JiD3al2I',
npm warn cleanup     [Error: ENOTDIR: not a directory, scandir '/work/app/node_modules/.lib-a-JiD3al2I/index.js'] {
...
changed 1 package in 279ms

残った .パッケージ名-xxxx のフォルダーは、次の npm install の邪魔になることがあるので、原因を外してから消します。

直し方:原因を外してから node_modules を作り直す

# Linux・Mac
sudo chattr -i node_modules/lib-a   # 属性が原因のときだけ
rm -rf node_modules
npm install
added 1 package in 277ms
$ node -e "console.log(require('lib-a'))"
v1.0.1

Windows では、先にエディター(VS Code など)、npm run dev などの開発サーバー、プロジェクトを開いているエクスプローラーのウィンドウを閉じ、PowerShell なら Remove-Item -Recurse -Force node_modules で消してから npm install します。package-lock.json は消さずに残すと、同じ版がそろいます。

npm cacheのEPERMとnpm cache verify・clean --force

この節では、npm のキャッシュで EPERM が出たときの見え方と、npm cache verify・clean --force の使い分けが分かります。

npm のキャッシュ(Linux・Mac は ~/.npm/_cacache)の中に、消せない・書けないファイルがあると、キャッシュを使うたびにエラーになります。手元では、キャッシュの中の content-v2/sha512 と index-v5 のフォルダーに変更不可の属性を付け、root で3つのコマンドを試しました。

$ npm cache add ./pkgs/lib-a-1.0.1.tgz
npm error code EEXIST
npm error syscall mkdir
npm error path /work/cache/_cacache/content-v2/sha512/6d
npm error errno -1
npm error EPERM: operation not permitted, mkdir '/work/cache/_cacache/content-v2/sha512/6d'
npm error File exists: /work/cache/_cacache/content-v2/sha512/6d
npm error Remove the existing file and try again, or run npm
npm error with --force to overwrite files recklessly.

code の行は EEXIST ですが、errno は -1、メッセージは EPERM でした。「File exists」とあっても、そのパスにファイルはありません。npm error の code 行だけで判断せず、errno とメッセージの行も読むのが近道です。

$ npm cache clean --force
npm warn using --force Recommended protections disabled.
npm error code EPERM
npm error syscall rmdir
npm error path /work/cache/_cacache/index-v5/b1
npm error errno -1
npm error
npm error Your cache folder contains root-owned files, due to a bug in
npm error previous versions of npm which has since been addressed.
npm error
npm error To permanently fix this problem, please run:
npm error   sudo chown -R 0:0 "/work/cache"

clean --force では code EPERM になり、「root の持ち物のファイルがある」として sudo chown を勧める文が出ました。この再現では root で実行しており、本当の原因は属性なので、表示どおりに chown しても直りません。EPERM・EACCES のときに npm が出す chown の案内は、原因の候補の1つとして読み、ls -l と lsattr で確かめてから手を打ちます。

直したあとの出力

属性を外してから npm cache verify を実行すると、キャッシュの点検と整理が通り、cache add も終了コード 0 で終わりました。

$ sudo chattr -i /work/cache/_cacache/content-v2/sha512 /work/cache/_cacache/index-v5
$ npm cache verify
Cache verified and compressed (/work/cache/_cacache)
Content verified: 0 (0 bytes)
Index entries: 0
Finished in 0.038s
$ npm cache add ./pkgs/lib-a-1.0.1.tgz; echo "exit=$?"
exit=0
コマンド していること 使う場面
npm cache verify中身を点検し、壊れた・不要なデータを整理最初に試す。消しすぎない
npm cache clean --forceキャッシュを丸ごと消すverify で直らないとき
--cache フォルダー(一時的)別のキャッシュの場所を使う今のキャッシュを触れないとき
sudo chown -Rキャッシュの持ち主を自分に戻すls -l で root の持ち物が見えたとき

キャッシュに手を付けられないときは、npm install --cache /tmp/npm-cache-$(id -u) のように、自分だけの一時的なキャッシュで切り分けられます。それで通るなら、原因はキャッシュの中です。一般ユーザーで、root の持ち物のキャッシュを使ったときは、EPERM ではなく EACCES(syscall mkdir)になりました。この場合の直し方は関連記事「npm EACCES: permission denied の直し方」で扱っています。

WindowsのEPERM(使用中のファイル・ウイルス対策・管理者権限)

この節では、Windows で EPERM が特に多い理由と、Windows での確かめ方・直し方が分かります。

Windows で EPERM が多いのは、Windows の「アクセスが拒否されました」(ERROR_ACCESS_DENIED)が、Node.js では EPERM に置き換えられて表示されるからです。Node.js が使っている libuv のソース(src/win/error.c)には、Windows のエラー番号との対応が次のように書かれています。

case ERROR_ACCESS_DENIED:               return UV_EPERM;
case ERROR_PRIVILEGE_NOT_HELD:          return UV_EPERM;
case ERROR_LOCK_VIOLATION:              return UV_EBUSY;
case ERROR_SHARING_VIOLATION:           return UV_EBUSY;
case ERROR_ELEVATION_REQUIRED:          return UV_EACCES;
Windows のエラー Microsoft Learn の説明 Node.js での表示
ERROR_ACCESS_DENIED(5)アクセスが拒否されました。EPERM
ERROR_SHARING_VIOLATION(32)ファイルは別のプロセスで使用されているため、このプロセスからアクセスすることはできません。EBUSY
ERROR_LOCK_VIOLATION(33)別のプロセスがファイルの一部をロックしているため、プロセスはこのファイルにアクセスできません。EBUSY
ERROR_PRIVILEGE_NOT_HELD(1314)クライアントには必要な特権がありません。EPERM

つまり Windows の EPERM は、Linux の EPERM(所有者・特権)よりも範囲が広く、「読み取り専用」「使用中のフォルダーの rename」「管理者のフォルダーへの書き込み」なども含みます。同じ「使用中」でも、Windows が返す番号によって EPERM になったり EBUSY になったりします。

Linux では「開いたまま」でも消せた

Linux では、別のプロセスがファイルを開いていても、rename・削除が通りました。開いていた側は、消されたあとも中身を読めています。

開いたまま fd = 20
別プロセスの rename: OK
別プロセスの unlink: OK
開いていた fd から読む: busy

このため、Windows の「エディターや開発サーバーがファイルを掴んでいて EPERM」は、Linux・Mac では同じ形では起きません。チームの中で Windows の人だけ npm install が失敗する、というときはこの違いを疑います。

Windows での直し方の順番

  1. 1ファイルを使っているプログラムを閉じるVS Code などのエディター、npm run dev・テストの監視、エクスプローラーのプレビュー、別のターミナルで動く node
  2. 2node_modules を消して入れ直す途中で止まった残り(.パッケージ名-xxxx)も一緒に消す。package-lock.json は残す
  3. 3読み取り専用の属性を確かめるNode.js 公式は、Windows の chmod は書き込みの許可だけを変えられると説明している
  4. 4保存場所を変えるC:\ 直下や Program Files ではなく、ユーザーのフォルダーの下にプロジェクトを置く
  5. 5ウイルス対策の影響を確かめる除外は組織の方針に従い、範囲をできるだけ狭くする
  6. 6最後に管理者のターミナル毎回管理者で npm を動かすと、作られたファイルの持ち主がずれる原因になる

ウイルス対策の除外について、Microsoft Learn の Microsoft Defender の説明は、除外は保護に穴を開けるものなので必要な問題を解くときだけ使い、プロセスではなくパスでできるだけ狭く指定するよう勧めています。ビルドツールの実行ファイルそのものを除外すると、そのプロセスのすべての操作が検査されなくなる、とも書かれています。

Node.js 公式ドキュメントにある Windows の EPERM

  • 隠しファイルを 'w' フラグ(fs.writeFile の既定)で開くと EPERM になる。既存の隠しファイルは 'r+' フラグで開けば書き込める。
  • fs.mkdir('/', { recursive: true }) は、Windows ではルートに対して EPERM(mkdir 'C:\')になる。
  • fs.watch で監視しているフォルダーが消されると EPERM が報告される。

隠しファイル(.env を隠し属性にしている場合など)への書き込みで EPERM が出たら、この1つ目に当てはまります。

symlinkのEPERM(Windowsの開発者モード・ハードリンクの保護)

この節では、シンボリックリンクやハードリンクを作るときの EPERM の原因と直し方が分かります。

Windows でシンボリックリンクを作るには、「シンボリック リンクの作成」の特権(SeCreateSymbolicLinkPrivilege)が要ります。Microsoft Learn によれば、クライアントの既定でこの特権を持つのは Administrators グループです。特権が無いときの ERROR_PRIVILEGE_NOT_HELD は、上の対応表のとおり Node.js では EPERM になります。npm link など、内部でシンボリックリンクを作るコマンドでは、この EPERM が出る可能性があります。

特権が無くても作れる方法

開発者モードを有効にする

フォルダーなら type に 'junction'(ジャンクション)

ジャンクションの先は絶対パスで指定する

特権で作る方法

管理者として開いたターミナルで実行

管理者で作ったファイルの持ち主に注意

毎回の作業には向かない

開発者モードの場所は、Microsoft Learn によると、Windows 11 では「設定」の「システム」→「詳細設定」の「開発者向け」セクションです(Windows 11 25H2 より前の版は「開発者向け」のページ)。Microsoft Learn の CreateSymbolicLink の説明には、特権の無いプロセスでリンクを作るためのフラグ(SYMBOLIC_LINK_FLAG_ALLOW_UNPRIVILEGED_CREATE)は、開発者モードが有効でなければ働かないと書かれています。

Node.js の fs.symlink の type 引数は Windows でだけ使われ、'dir'・'file'・'junction' を指定できます。Node.js 公式ドキュメントには、ジャンクションの先は絶対パスにする必要があると書かれています。

// Windows でフォルダーへのリンクを特権なしで作る(ジャンクション)
const fs = require('fs');
const path = require('path');
fs.symlinkSync(path.resolve('packages/shared'), 'node_modules/shared', 'junction');

Linux のハードリンクも EPERM になる

Linux では、シンボリックリンクは他人のファイルにも作れますが、ハードリンクは保護されていることがあります。手元の環境は /proc/sys/fs/protected_hardlinks が 1 で、nobody から root のファイル(rw-r--r--)へのハードリンクは EPERM でした。

[EPERM] ハードリンク 他人のファイル
       EPERM: operation not permitted, link '/work/own/rootfile.txt' -> '/work/own/hl.txt'  (errno -1, syscall link)

Linux のマニュアル(proc_sys_fs)では、この設定が 1 のとき、ハードリンクを作れるのは「持ち主である」か「読み書きできる通常のファイルである」などの条件を満たす場合だけです。ビルドツールがキャッシュからハードリンクで node_modules を作る場合に出ることがあり、コピーかシンボリックリンクにすると避けられます。シンボリックリンクの基本は関連記事「Linuxシンボリックリンクln -sの使い方|作成・削除・確認一覧」で扱っています。

MacのOperation not permittedとuv_cwd

この節では、Mac で EPERM・Operation not permitted が出る典型と、uv_cwd のエラーの読み方が分かります。

Mac では、フォルダーを unlink しようとしたときにも EPERM になります。Apple の unlink(2) のマニュアルには「The named file is a directory and the effective user ID of the process is not the super-user.」とあります。Linux では同じ操作が EISDIR でした。

[EISDIR] unlink ディレクトリ(Linux で実行)
       EISDIR: illegal operation on a directory, unlink '/work/imm'  (errno -21, syscall unlink)

Linux で動くコードが Mac でだけ EPERM unlink になるなら、フォルダーを fs.unlink で消そうとしていないかを確かめ、fs.rmSync(dir, { recursive: true }) か fs.rmdir に変えます。

デスクトップ・書類・ダウンロードのフォルダーで出るとき

Mac には、アプリごとに特定の場所のファイルへのアクセスを許可する仕組みがあります。Apple サポートの「Macでファイルおよびフォルダへのアクセスを制御する」によると、確かめる場所は次のとおりです。

  1. アップルメニュー →「システム設定」→ サイドバーの「プライバシーとセキュリティ」
  2. 「ファイルとフォルダ」
  3. アプリ(ターミナルや VS Code など)ごとに、場所へのアクセスのオン・オフを切り替える

ターミナルからデスクトップや書類の中のプロジェクトを操作して Operation not permitted が出るときは、ここでそのアプリが許可されているかを見ます。プロジェクトをホームの下の別のフォルダー(例:~/dev)に置くのも1つの方法です。

uv_cwd のエラーは「今いるフォルダー」が取れない

エラー文の syscall が uv_cwd のときは、Node.js が起動時に「今いるフォルダー」を OS から取得できなかったことを示します。手元の Linux で、今いるフォルダーを別のターミナルから消して node を起動すると、次のようになりました。

Error: ENOENT: no such file or directory, uv_cwd
  errno: -2,
  code: 'ENOENT',
  syscall: 'uv_cwd'

Mac などで uv_cwd に EPERM が付いて出た場合も、「今いるフォルダーを OS から取得できなかった」という点は同じです。どちらの場合も、まず cd ~ で確実にあるフォルダーに移ってから、プロジェクトのフォルダーに cd し直してコマンドを実行します。git のブランチの切り替えや、別のターミナルでフォルダーを作り直したあとに起きやすい形です。

EPERM・EACCES・EBUSY・EROFSの違い(プロセスの操作も含む)

この節では、名前の似たエラーとの違いを実物で比べ、どのエラーなら何を直すのかが分かります。

EACCES は「読み書きの許可が無い」、EPERM は「持ち主・特権・属性で断られた」、EBUSY は「使用中」、EROFS は「読み取り専用のファイルシステム」です。Node.js 公式ドキュメントの EACCES の説明は「An attempt was made to access a file in a way forbidden by its file access permissions.」で、ファイルのアクセス許可(rwx)に触れています。

手元で実際に起こした原文を並べます。EBUSY と EROFS は、unshare で作った専用のマウント名前空間の中で、作業用のフォルダーにだけ tmpfs と読み取り専用のマウントをして試しました。

[EBUSY] rmdir マウント中のフォルダー
       EBUSY: resource busy or locked, rmdir '/work/mnt'  (errno -16, syscall rmdir)
[EBUSY] rename マウント中のフォルダー
       EBUSY: resource busy or locked, rename '/work/mnt' -> '/work/mnt2'  (errno -16, syscall rename)
[EROFS] 書き込み 読み取り専用マウント
       EROFS: read-only file system, open '/work/ro/src/a.txt'  (errno -30, syscall open)
[EROFS] unlink 読み取り専用マウント
       EROFS: read-only file system, unlink '/work/ro/src/a.txt'  (errno -30, syscall unlink)
エラー errno 意味 手元で起きた操作 直す場所
EPERM-1持ち主・特権・属性で断られた他人のファイルの chmod、スティッキーの削除持ち主・属性
EACCES-13読み書き・実行の許可が無い644 の他人のファイルへの書き込み、ポート80rwx・フォルダーの権限
EBUSY-16使用中で操作できないマウント中のフォルダーの rmdir使っているもの
EROFS-30読み取り専用のファイルシステム読み取り専用マウントへの書き込みマウントの設定
EISDIR-21フォルダーに対するファイルの操作Linux でフォルダーを unlink呼ぶ関数

プロセスの操作の EPERM と、ポートの EACCES

EPERM はファイル以外でも出ます。nobody から root のプロセスに process.kill を送ると EPERM、process.setuid(0) も EPERM でした。一方、1024 番未満のポートで待ち受けようとすると EACCES でした。

[EPERM] process.setuid(0)
       EPERM, Operation not permitted  (errno 1, syscall setuid)
[EPERM] process.kill(4577) 他人のプロセス
       kill EPERM  (errno -1, syscall kill)
[EACCES] listen 80
       listen EACCES: permission denied 127.0.0.1:80  (errno -13, syscall listen)

開発中に「前に起動したサーバーを止めたい」と kill して EPERM になるなら、そのプロセスは sudo など別のユーザーで起動されています。ps -o pid,user,comm -p プロセスID で持ち主を確かめ、同じユーザー(sudo)で止めます。ポートを使っているプロセスの探し方は関連記事「ポートを使っているプロセスの調べ方|ss・lsof・netstat比較」で扱っています。

ファイルが見つからないときの ENOENT は、同じ第49弾の記事「ENOENT: no such file or directoryの直し方|npm」で扱っています。

EPERMを起こさない書き方(fs.rmのmaxRetries・sudo npmを避ける)

この節では、EPERM を減らすコードと運用の書き方と、リトライで直るもの・直らないものの見分け方が分かります。

fs.rm の maxRetries は、一時的な EPERM(Windows で一瞬だけファイルが使用中など)には効きますが、属性や持ち主が原因の EPERM には効きません。Node.js 公式ドキュメントは、maxRetries について「EBUSY、EMFILE、ENFILE、ENOTEMPTY、EPERM が出たら、retryDelay ミリ秒ずつ長くしながら再試行する。recursive が true でなければ無視される」と説明しています。

手元で、変更不可の属性を付けたファイルを含むフォルダーを fs.rmSync で消そうとした結果です。

{"recursive":true} -> ENOTDIR scandir ENOTDIR: not a directory, scandir '/work/imm2/sub/lock.txt' 0ms
{"recursive":true,"maxRetries":3,"retryDelay":100} -> ENOTDIR scandir ENOTDIR: not a directory, scandir '/work/imm2/sub/lock.txt' 603ms
promises.rm maxRetries 3 -> ENOTDIR scandir ENOTDIR: not a directory, scandir '/work/imm2/sub/lock.txt' 5ms

maxRetries: 3 の同期版は、100・200・300ms と待って合計603msかかりましたが、結果は同じでした。ここでも表示は ENOTDIR で、strace では OS が返したのは EPERM(unlink と rmdir)でした。

unlink("/work/imm2/sub/lock.txt") = -1 EPERM (Operation not permitted)
rmdir("/work/imm2/sub/lock.txt") = -1 EPERM (Operation not permitted)
openat(AT_FDCWD, "/work/imm2/sub/lock.txt", O_RDONLY|O_NONBLOCK|O_CLOEXEC|O_DIRECTORY) = -1 ENOTDIR (Not a directory)

リトライは、Windows で開発サーバーやウイルス対策が一瞬ファイルを開いている、といった時間で解ける原因のためのものです。次のように、EPERM・EBUSY だけを扱い、回数に上限を付けます。

const fs = require('fs');

function removeDir(dir) {
  try {
    // Windows で一瞬だけ使用中になる場合に備える
    fs.rmSync(dir, { recursive: true, force: true, maxRetries: 5, retryDelay: 200 });
  } catch (e) {
    if (e.code === 'EPERM' || e.code === 'EBUSY' || e.code === 'ENOTDIR') {
      throw new Error(`消せませんでした: ${dir}(${e.code})。開いているプログラム・属性・持ち主を確かめてください`, { cause: e });
    }
    throw e;
  }
}
  • 1npm install に sudo を付けないroot の持ち物のファイルが node_modules やキャッシュに残り、次の EPERM・EACCES の原因になる
  • 2グローバルのインストール先を自分のフォルダーにするnvm などで入れた Node.js なら、npm install -g も一般ユーザーで済む
  • 3一時ファイルは mkdtemp の自分のフォルダーに置く/tmp の固定名は、他人のファイルと衝突してスティッキーの EPERM になる
  • 4コピーで権限・時刻を保つ処理は、行き先の持ち主を確かめる他人のファイルへの chmod・utimes で EPERM になる
  • 5エラーは e.code だけでなく errno・syscall も記録するnpm・fs.rm の表示が EPERM でない場合がある

判断表:EPERMが出たらどこから確かめるか

この節では、エラー文と環境から、最初に確かめる場所を順番に決められます。

上から順に当てはまるかを見ていくと、ほとんどの EPERM は3つ目までで原因が分かります。

  1. 1Windows → 使用中のプログラムエディター・開発サーバー・エクスプローラーを閉じ、node_modules を作り直す
  2. 2syscall が chmod・chown・utime → 持ち主ls -l の3列目と id を比べ、chown で戻す
  3. 3sudo でも出る → 属性lsattr で i・a を見る。理由を確かめて chattr で外す
  4. 4unlink・rename で、フォルダーの末尾が t → スティッキー持ち主に消してもらうか、自分のフォルダーを使う
  5. 5symlink → 特権Windows は開発者モードかジャンクション、Linux のハードリンクはコピーに
  6. 6npm cache → 点検してから消すnpm cache verify、直らなければ持ち主・属性、最後に clean --force
  7. 7表示が ENOTDIR・EEXIST で納得できない → straceOS が最初に返したエラーを見る。Windows は debug-0.log

OS・環境ごとに、起きやすい EPERM と確かめるコマンドをまとめます。

環境 起きやすい EPERM 確かめること
Windowsnpm install の rename・unlink、symlink開いているプログラム、読み取り専用、開発者モード
Macフォルダーの unlink、保護された場所fs.rm に変える、「ファイルとフォルダ」の許可
Linuxchmod・chown、スティッキー、属性ls -l、ls -ld でフォルダーの t、lsattr
Dockerバインドマウントのファイルの権限コンテナのユーザーとホストのファイルの持ち主
CIキャッシュの復元後の npm installキャッシュを作ったユーザーと実行するユーザー

Docker のバインドマウントでの権限の問題は、関連記事「Docker bind mountのPermission deniedの直し方」で扱っています。

よくある質問

この節では、EPERM について検索でよく調べられる疑問に、短く答えます。

Q. EPERM は何の略ですか。
POSIX で決まっているエラーの名前です。名前の由来を説明した公式の文書は見当たりませんでしたが、メッセージは Operation not permitted(操作が許可されていない)です。Linux では番号 1 で、Node.js のエラーでは errno: -1 と表示されました。

Q. EPERM と EACCES の違いは何ですか。
EACCES は読み書き・実行の許可(rwx)が無いとき、EPERM は持ち主でない・特権が要る・属性で守られているときです。手元では、同じ他人のファイルでも、書き込みは EACCES、chmod は EPERM でした。

Q. sudo を付けても EPERM が出ます。
Linux なら、変更不可(i)・追記のみ(a)の属性を lsattr で確かめます。root でも書き換え・削除・rename が EPERM になりました。Windows なら、ほかのプログラムがファイルを使っている可能性が高いです。

Q. npm install で EPERM: operation not permitted, rename が出ます(Windows)。
エディター、npm run dev などの開発サーバー、プロジェクトを開いているエクスプローラーを閉じてから、node_modules を消して npm install し直します。続くときは、プロジェクトを C:\ 直下からユーザーのフォルダーの下へ移します。

Q. npm cache clean --force で直りますか。
キャッシュの中のデータが原因なら直りますが、まずは npm cache verify を試します。手元では、キャッシュの中に消せないファイルがあると clean --force 自体が EPERM になりました。その場合は持ち主・属性を直すのが先です。

Q. npm が「sudo chown -R」を勧めてきます。従ってよいですか。
ls -l でキャッシュの中に root の持ち物のファイルが見えるなら、その案内で直ります。手元の再現では原因が属性だったので、chown では直りませんでした。実行する前に、表示されたパスが自分のキャッシュであることも確かめます。

Q. 管理者として実行すれば必ず直りますか。
特権が要る操作(Windows のシンボリックリンクなど)は直ります。ファイルが使用中の場合や、Linux の属性が原因の場合は直りません。管理者で作ったファイルは、あとで一般ユーザーから消せなくなることがあるので、最後の手段にします。

Q. Mac で rm しても Operation not permitted になります。
そのフォルダーがスティッキー(ls -ld の末尾が t)で他人のファイルか、ターミナルにその場所へのアクセスが許可されていない可能性があります。「システム設定」の「プライバシーとセキュリティ」→「ファイルとフォルダ」を確かめます。

Q. エラーの表示は ENOTDIR なのに、この記事の原因に当てはまるのはなぜですか。
npm や fs.rm は、削除が断られたあとに別の方法を試し、最後に失敗した操作のエラーを表示することがあります。手元では、OS は EPERM を返していたのに、表示は ENOTDIR でした。Linux では strace で最初のエラーを確かめられます。

Q. EPERM をコードで無視して続けてもよいですか。
キャッシュや一時ファイルの片付けなど、失敗しても結果が変わらない処理なら、e.code を見て警告に留めるのが一般的です。設定ファイルの保存のように、失敗すると結果が誤る処理では、パスと syscall をエラー文に入れて止めるほうが原因を早く見つけられます。

まとめ

  • EPERM: operation not permitted は「持ち主か特権が要る操作を断られた」という OS のエラー。syscall と path が手がかり。
  • Linux・Mac の主な原因は、他人のファイルへの chmod・chown・utimes、スティッキーのフォルダーでの削除・rename、変更不可の属性。属性は root でも EPERM になる。
  • Windows は「アクセスが拒否されました」が EPERM になるため範囲が広い。使用中のプログラムを閉じ、node_modules を作り直すのが最初の手。symlink は開発者モードかジャンクション。
  • npm cache の EPERM は npm cache verify から。npm の chown の案内は候補の1つとして、ls -l・lsattr で確かめてから従う。
  • npm・fs.rm の表示は ENOTDIR・EEXIST になることがある。errno の行と strace で、OS が最初に返したエラーを確かめる。

参考・出典

確認日はいずれも 2026年11月5日です。

  • Node.js v22 Documentation「Errors」Common system errors:https://nodejs.org/docs/latest-v22.x/api/errors.html#common-system-errors
  • Node.js v22 Documentation「File system」(fs.rm の maxRetries・Windows の隠しファイル・fs.chmod の注意・fs.symlink の type):https://nodejs.org/docs/latest-v22.x/api/fs.html
  • libuv「src/win/error.c」(Windows のエラー番号との対応):https://github.com/libuv/libuv/blob/v1.x/src/win/error.c
  • Linux man-pages「unlink(2)」:https://man7.org/linux/man-pages/man2/unlink.2.html
  • Linux man-pages「chmod(2)」:https://man7.org/linux/man-pages/man2/chmod.2.html
  • Linux man-pages「proc_sys_fs(5)」protected_hardlinks:https://man7.org/linux/man-pages/man5/proc_sys_fs.5.html
  • Apple「unlink(2)」:https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man2/unlink.2.html
  • Apple サポート「Macでファイルおよびフォルダへのアクセスを制御する」:https://support.apple.com/ja-jp/guide/mac-help/mchld5a35146/mac
  • Microsoft Learn「システム エラー コード (0-499)」:https://learn.microsoft.com/ja-jp/windows/win32/debug/system-error-codes--0-499-
  • Microsoft Learn「Create symbolic links」(SeCreateSymbolicLinkPrivilege):https://learn.microsoft.com/ja-jp/previous-versions/windows/it-pro/windows-10/security/threat-protection/security-policy-settings/create-symbolic-links
  • Microsoft Learn「CreateSymbolicLinkW function」:https://learn.microsoft.com/en-us/windows/win32/api/winbase/nf-winbase-createsymboliclinkw
  • Microsoft Learn「開発用にデバイスを有効にする」:https://learn.microsoft.com/ja-jp/windows/apps/get-started/enable-your-device-for-development
  • Microsoft Learn「Microsoft Defender Antivirus exclusions overview」:https://learn.microsoft.com/en-us/defender-endpoint/microsoft-defender-antivirus-exclusions-overview
  • npm Docs「Common errors」:https://docs.npmjs.com/common-errors

本記事の内容は、ご自由にお使いください。
ご利用の際は、出典として本ページへのリンクを記載いただけますようお願いします。

(記載例)出典:株式会社RJC「EPERM: operation not permittedの直し方|npm」

株式会社RJC ― SI事業・SES事業・AI駆動開発。RJCは一緒に成長を楽しめる会社です。

WE ARE HIRING

RJCで一緒に開発しながら、
成長を楽しみませんか?

RJCは、Web・モバイル・AIを活用した開発プロジェクトで、テックリードやPM・PMOも活躍するシステム開発会社です。会社を知る、待遇を確かめる、話を聞いてみる。気になるところ見てみてください!

  • 127日年間休日
  • 12時間平均残業時間
  • 毎日ガチャ遊びココロも大切にする福利厚生。アマギフなどの賞品ラインナップ!

ほかにも、チケットレストラン、書籍読み放題、2年ごとの慰労報奨(休暇 or 金一封)、11期連続の黒字決算。

ABOUT RJC RJCがどんな会社か知る 考え方、研修、働き方、福利厚生、社員の前職まで。RJCのことが丸わかり! RJC丸わかりページへ JOB DESCRIPTION 仕事内容・待遇を見てみる 仕事内容、給与・待遇、選考の流れ。経験者も未経験も!応募前に知りたいこと、まとめました! 募集要項を見る ENTRY エントリーする エントリーは1〜2分・履歴書不要です。まずは話を聞いてみたい、という方でも歓迎です! エントリーフォームへ

成長のヒミツ、 ぜんぶ丸わかり