Pythonのshutilの使い方|ファイル・フォルダーのコピー・移動・削除と注意点
Python で「ファイルをバックアップ用のフォルダーにコピーしたい」「フォルダーを丸ごと別の場所に移したい」「古いログをまとめて消したい」ときは、標準ライブラリの shutil(シェル・ユーティリティの略)を使います。関数ごとにコピーされる情報が違ったり、確認なしで上書き・削除したりする落とし穴もあります。
この記事では、Windows 11 の Python 3.12 で実際に動かした結果つきで、copy・copy2・copyfile の違い、コピー先の書き方で変わる動き、copytree での除外と上書き、move の上書き、rmtree が読み取り専用ファイルで止まるときの直し方(onexc)、disk_usage・which、削除の前に一覧だけ出す「ドライラン」を解説します(2026 年 10 月に確認)。
パスの組み立てや 1 ファイルの読み書きは「Pythonのpathlibの使い方」、ZIP にまとめる方法は「Pythonのzipfileの使い方」で解説しています。この記事はコピー・移動・削除に絞ります。
shutil とは:pathlib との役割分担
pathlib の Path は、パスの組み立てや、1 ファイルの読み書き・名前の変更・削除が得意です。一方、Python 3.12 の pathlib にはコピーするメソッドがなく、中身の入ったフォルダーを消すメソッドもありません。そこを受け持つのが shutil です。

shutil の関数には文字列のパスも Path も渡せるので、「Path でパスを作り、shutil でコピーする」のがよくある組み合わせです。サンプルは、練習用の空のフォルダーに sample.py などの名前で保存し、PowerShell でそのフォルダーに移動してから py sample.py で実行します。コピー・移動・削除を試すときは、必ず練習用のフォルダーの中で行ってください。
ファイルをコピーする:copy・copy2・copyfile
ファイル 1 つをコピーする関数は 3 つあります。公式ドキュメントでは、copyfile は「中身だけ(メタデータなし)」、copy は「中身と権限(パーミッション)」、copy2 は「copy に加えてメタデータもできるだけ残す」と説明されています。メタデータとは、更新日時などの「ファイルの中身以外の情報」のことです。
元のファイルの更新日時を 2026-04-01 9:00 にしてから 3 つの関数でコピーし、stat() で更新日時(st_mtime)を比べました。
import os
import shutil
from datetime import datetime
from pathlib import Path
src = Path("report.txt")
src.write_text("売上レポート\n", encoding="utf-8")
old = datetime(2026, 4, 1, 9, 0).timestamp()
os.utime(src, (old, old)) # 練習のため、更新日時を 2026-04-01 9:00 にする
shutil.copyfile(src, "by_copyfile.txt")
shutil.copy(src, "by_copy.txt")
shutil.copy2(src, "by_copy2.txt")
for name in ["report.txt", "by_copyfile.txt", "by_copy.txt", "by_copy2.txt"]:
mtime = Path(name).stat().st_mtime
print(f"{name:16} {datetime.fromtimestamp(mtime):%Y-%m-%d %H:%M:%S}")
report.txt 2026-04-01 09:00:00
by_copyfile.txt 2026-10-23 15:37:54
by_copy.txt 2026-10-23 15:37:54
by_copy2.txt 2026-04-01 09:00:00
copyfile と copy では、更新日時が「コピーした時刻」になりました。copy2 だけが元の更新日時を残しています。バックアップのように「いつ更新されたファイルか」を残したいときは copy2 を使います。
権限の違いも試しました。os.chmod(src, stat.S_IREAD) で読み取り専用にしたファイルを copy でコピーすると、コピーも読み取り専用になり、copyfile ではふつうの書き込めるファイルになりました(os.access(name, os.W_OK) で確認)。まとめると次のとおりです。
| 関数 | 中身 | 権限(読み取り専用など) | 更新日時など | コピー先にフォルダーを書ける |
|---|---|---|---|---|
| copyfile(元, 先) | ○ | × | × | ×(ファイル名だけ) |
| copy(元, 先) | ○ | ○ | × | ○ |
| copy2(元, 先) | ○ | ○ | ○(できる範囲で) | ○ |
なお公式ドキュメントによると、copy2 でも Windows ではファイルの所有者・ACL(アクセス権の設定)・代替データストリームはコピーされません。迷ったら copy2、中身だけでよいなら copyfile と覚えておけば十分です。
コピー先は「フォルダー」か「ファイル名」かで動きが変わる
copy と copy2 は、コピー先にすでにあるフォルダーを書くと、その中に同じ名前でコピーします。それ以外は「そのファイル名で作る」と解釈されます。backup フォルダーを作ってから試しました(3 つ目の bakup は、backup の書き間違いのつもりです)。
import shutil
from pathlib import Path
Path("memo.txt").write_text("memo\n", encoding="utf-8")
Path("backup").mkdir(exist_ok=True)
print(shutil.copy("memo.txt", "backup"))
print(shutil.copy("memo.txt", "backup/memo_old.txt"))
print(shutil.copy("memo.txt", "bakup"))
print(Path("bakup").is_file())
backup\memo.txt
backup/memo_old.txt
bakup
True
戻り値はコピーしてできたファイルのパスです。1 つ目は backup の中に memo.txt ができ、2 つ目は名前を変えてコピーされました。注意したいのは 3 つ目で、フォルダー名を書き間違えると、エラーにならずに「bakup」という拡張子なしのファイルができます。フォルダーにコピーしたいときは、先に Path("backup").is_dir() で確かめると安全です。
コピー先でよく出るエラー
コピー先の書き方を 4 通り変えて、出たエラーを try・except で受け取って表示しました(例外の受け取り方は「Pythonの例外処理入門」を参照)。左がどの関数にどう渡したか、右が出たエラーです。
copy('memo.txt', 'newdir/memo.txt') -> FileNotFoundError: [Errno 2] No such file or directory: 'newdir/memo.txt'
copy('memo.txt', 'newdir/') -> OSError: [Errno 22] Invalid argument: 'newdir/'
copyfile('memo.txt', 'backup') -> PermissionError: [Errno 13] Permission denied: 'backup'
copy('memo.txt', 'memo.txt') -> SameFileError: 'memo.txt' and 'memo.txt' are the same file
| エラー | 原因 | 直し方 |
|---|---|---|
| FileNotFoundError | コピー先のフォルダー(newdir)がない。copy はフォルダーを作らない | 先に dst.parent.mkdir(parents=True, exist_ok=True) |
| OSError: Invalid argument(Windows) | ないフォルダーの名前の最後に / を付けた | 同上。フォルダーを作ってから渡す |
| PermissionError | copyfile のコピー先にフォルダーを書いた | copyfile にはファイル名まで書く。フォルダーなら copy・copy2 |
| SameFileError | コピー元とコピー先が同じファイル | コピー先の名前を変える |
copyfile にフォルダーを渡したときの PermissionError は Windows で試した結果で、公式ドキュメントは「コピー先はファイル名まで書く」「書き込めない場所なら OSError」とだけ書いています。
また、copy・copy2・copyfile はコピー先に同じ名前のファイルがあると、確認なしで上書きします(公式ドキュメントにも「すでにあれば置き換える」とあります)。上書きしたくないときは、コピーの前に dst.exists() で確かめます。
フォルダーごとコピーする:copytree
フォルダーを中身ごとコピーするには copytree を使います。__pycache__(Python のキャッシュ)入りの myapp フォルダーで試しました。
from pathlib import Path
app = Path("myapp")
(app / "src" / "__pycache__").mkdir(parents=True, exist_ok=True)
(app / "data").mkdir(exist_ok=True)
(app / "README.md").write_text("# myapp\n", encoding="utf-8")
(app / "src" / "main.py").write_text('print("main")\n', encoding="utf-8")
(app / "src" / "__pycache__" / "main.cpython-312.pyc").write_bytes(b"\x00" * 16)
(app / "data" / "users.csv").write_text("id,name\n1,sato\n", encoding="utf-8")
import shutil
from pathlib import Path
print(shutil.copytree("myapp", "myapp_backup"))
for p in sorted(Path("myapp_backup").rglob("*")):
print(" ", p.as_posix())
myapp_backup
myapp_backup/data
myapp_backup/data/users.csv
myapp_backup/README.md
myapp_backup/src
myapp_backup/src/__pycache__
myapp_backup/src/__pycache__/main.cpython-312.pyc
myapp_backup/src/main.py
copytree は、コピー先のフォルダーがまだないことが前提です。同じコードをもう一度実行すると FileExistsError: [WinError 183] 既に存在するファイルを作成することはできません。: 'myapp_backup' で止まりました。ファイルは copy2 でコピーされる(公式ドキュメントのとおり)ので、更新日時も残ります。
いらないものを除外する:ignore_patterns
ignore に shutil.ignore_patterns(...) を渡すと、* などのワイルドカードに合うファイル・フォルダーをコピーしません。.pyc ファイルと __pycache__ フォルダーを除外しました。
import shutil
from pathlib import Path
shutil.copytree(
"myapp",
"myapp_clean",
ignore=shutil.ignore_patterns("*.pyc", "__pycache__"),
)
for p in sorted(Path("myapp_clean").rglob("*")):
print(" ", p.as_posix())
myapp_clean/data
myapp_clean/data/users.csv
myapp_clean/README.md
myapp_clean/src
myapp_clean/src/main.py
__pycache__ フォルダーごと消えています。パターンは名前(パスではなくファイル名・フォルダー名)と比べられるので、”src/*.pyc” のようにフォルダーを含めて書く必要はありません。仮想環境の .venv や .git なども、同じように並べて除外できます。
既存のフォルダーに上書きする:dirs_exist_ok=True
Python 3.8 で追加された dirs_exist_ok=True を付けると、コピー先のフォルダーがあっても続けて、同じ名前のファイルを上書きします。バックアップ側の README.md を書き換え、バックアップにだけあるファイルを置き、元のフォルダーにはファイルを 1 つ足してから試しました。
import shutil
from pathlib import Path
backup = Path("myapp_backup")
(backup / "README.md").write_text("バックアップ側で書き換えた\n", encoding="utf-8")
(backup / "old_note.txt").write_text("バックアップにだけある\n", encoding="utf-8")
Path("myapp/src/util.py").write_text("# 新しく足したファイル\n", encoding="utf-8")
shutil.copytree("myapp", backup, dirs_exist_ok=True)
print((backup / "README.md").read_text(encoding="utf-8"), end="")
print((backup / "src" / "util.py").exists())
print((backup / "old_note.txt").exists())
# myapp
True
True
README.md は確認なしに上書きされ、util.py も入りましたが、バックアップにだけあった old_note.txt は残っています。dirs_exist_ok=True は「足して上書きする」だけで、元にないファイルを消してまったく同じにする(ミラーする)わけではありません。
移動する:move
move(元, 先) はファイルもフォルダーも移動でき、移動先のパスを返します。コピーと同じく、すでにあるフォルダーならその中に入り、それ以外は「その名前に変える」動きです。
import shutil
from pathlib import Path
Path("archive").mkdir(exist_ok=True)
Path("a.txt").write_text("A\n", encoding="utf-8")
print(shutil.move("a.txt", "archive"))
Path("a.txt").write_text("A2\n", encoding="utf-8")
try:
shutil.move("a.txt", "archive")
except shutil.Error as e:
print("shutil.Error:", e)
print(shutil.move("archive", "archive_2026"))
archive\a.txt
shutil.Error: Destination path 'archive\a.txt' already exists
archive_2026
フォルダーの中に同じ名前のファイルがあると、shutil.Error で止まりました。最後は archive フォルダーが中身ごと archive_2026 になりました。
移動先に同じ名前のファイルがあると上書きされる(Windows)
では、移動先にファイル名を書いて、そこに同じ名前のファイルがあったらどうなるでしょうか。
import shutil
from pathlib import Path
Path("new.txt").write_text("新しい内容\n", encoding="utf-8")
Path("dest.txt").write_text("元からあった内容\n", encoding="utf-8")
print(shutil.move("new.txt", "dest.txt"))
print(Path("new.txt").exists())
print(Path("dest.txt").read_text(encoding="utf-8"), end="")
dest.txt
False
新しい内容
エラーにならず、dest.txt の元の内容は消えました。同じことを pathlib の Path("new.txt").rename("dest.txt") で試すと、Windows では FileExistsError: [WinError 183] 既に存在するファイルを作成することはできません。 で止まりました(rename と replace の違いは「Pythonのpathlibの使い方」を参照)。
理由は shutil.move の作りにあります。Python 3.12 のソースコードでは、move はまず os.rename を試し、OSError で失敗すると「copy2 でコピーしてから元を消す」方法に切り替えます。Windows の os.rename は移動先にファイルがあると失敗するので、代わりのコピーで上書きされるわけです。公式ドキュメントの「os.rename の動きによっては上書きされることがある」はこのことです。上書きしたくないときは、先に Path(移動先).exists() で確かめましょう。
同じドライブと別のドライブの違い
公式ドキュメントによると、移動先が同じファイルシステム(Windows ならふつうは同じドライブ)なら os.rename で名前を付け替えるだけなので、大きなファイルでもすぐ終わります。C: から D: のように別のファイルシステムへ移すときは、copy2(フォルダーなら copytree)でコピーしてから元を消すので、データの量だけ時間がかかります(別のドライブへの移動は、この記事では試していません)。
フォルダーを中身ごと削除する:rmtree
shutil.rmtree(フォルダー) は、フォルダーを中身ごと消します。確認なしで、ごみ箱にも入りません。ダミーのフォルダーを rmtree で消し、前後で Windows のごみ箱の項目数を数えましたが、3 件のまま変わりませんでした。間違えて消すと、ごみ箱からは戻せません。
Linux の rm -rf と同じくらい危険です。パスに空の文字列やユーザーの入力がそのまま入らないようにし、消す前に必ず print(target.resolve()) で対象を表示して確かめてください。
読み取り専用のファイルがあると PermissionError で止まる
Windows では、読み取り専用のファイルが 1 つでもあると rmtree が失敗します。logs フォルダーと読み取り専用の settings.ini を入れたフォルダーで試しました。
import os
import shutil
import stat
from pathlib import Path
target = Path("old_project")
(target / "logs").mkdir(parents=True, exist_ok=True)
(target / "logs" / "app.log").write_text("log\n", encoding="utf-8")
locked = target / "settings.ini"
locked.write_text("[app]\n", encoding="utf-8")
os.chmod(locked, stat.S_IREAD) # 読み取り専用にする
try:
shutil.rmtree(target)
except PermissionError as e:
print("PermissionError:", e)
print(sorted(p.as_posix() for p in target.rglob("*")))
PermissionError: [WinError 5] アクセスが拒否されました。: 'old_project\\settings.ini'
['old_project/settings.ini']
logs フォルダーと app.log はすでに消えていて、settings.ini だけが残っています。rmtree は失敗しても「全部消すか、何もしないか」にはならず、途中まで消えた状態で止まります。Git のリポジトリも要注意です。練習用に git init・git commit したフォルダーでは、.git\objects の中のファイルが読み取り専用になっていて、rmtree で同じ PermissionError(WinError 5)になりました。
onexc で読み取り専用を外してやり直す(Python 3.12 以降)
Python 3.12 で追加された onexc に関数を渡すと、消せなかったときにその関数が呼ばれます。関数は「失敗した関数・パス・例外」の 3 つを受け取ります。公式ドキュメントの例と同じく、読み取り専用を外してから同じ関数でやり直します。
import os
import shutil
import stat
from pathlib import Path
def remove_readonly(func, path, exc):
print("読み取り専用を外してやり直す:", func.__name__, path)
os.chmod(path, stat.S_IWRITE)
func(path)
target = Path("old_project")
shutil.rmtree(target,onexc=remove_readonly)
print(target.exists())
読み取り専用を外してやり直す: unlink old_project\settings.ini
False
ファイルを消す関数(unlink)が失敗したので remove_readonly が呼ばれ、読み取り専用を外して消せました。やり直しでも失敗したときは、そのエラーが呼び出し元まで伝わります。
Python 3.11 以前には onexc がないので、onerror を使います。3 つ目の引数が例外そのものではなく sys.exc_info() のタプルになる点だけが違い、上の remove_readonly は 3 つ目を使っていないので、そのまま onerror=remove_readonly と書けます(onerror は 3.12 で非推奨)。ignore_errors=True はエラーを無視するだけで、消せなかったファイルが黙って残ります。
削除の前に確認を挟む:ドライランの書き方
まとめて消す処理は、いきなり消さずに、まず「何を消すつもりか」の一覧だけを出すドライラン(予行演習)にすると安全です。次の関数は、logs フォルダー直下の、30 日より前に更新された .log ファイルを探します。dry_run=True(既定)のときは一覧を出すだけで、yes と入力したときだけ本当に消します。
import time
from pathlib import Path
def find_old(folder, pattern, days):
"""folder の直下で pattern に合い、days 日より前に更新されたファイルの一覧を返す"""
base = Path(folder).resolve()
limit = time.time() - days * 24 * 60 * 60
targets = [p for p in sorted(base.glob(pattern))
if p.is_file() and p.stat().st_mtime < limit]
return base, targets
def remove_old(folder, pattern, days, dry_run=True):
base, targets = find_old(folder, pattern, days)
print(f"{base.name} の {pattern}({days} 日より前): {len(targets)} 件")
for p in targets:
if p.parent != base: # 念のため、指定したフォルダーの外は消さない
raise ValueError(f"対象のフォルダーの外です: {p}")
print((" [ドライラン] " if dry_run else " 削除: ") + p.name)
if not dry_run:
p.unlink()
remove_old("logs", "*.log", 30)
answer = input("本当に削除しますか? yes と入力すると削除します: ")
if answer == "yes":
remove_old("logs", "*.log", 30, dry_run=False)
else:
print("中止しました")
print(sorted(p.name for p in Path("logs").iterdir()))
logs フォルダーに、114 日前の 2026-07-01.log、52 日前の 2026-09-01.log、3 日前の 2026-10-20.log、200 日前の keep.txt を用意して実行し、yes と入力した結果です。
logs の *.log(30 日より前): 2 件
[ドライラン] 2026-07-01.log
[ドライラン] 2026-09-01.log
本当に削除しますか? yes と入力すると削除します: yes
logs の *.log(30 日より前): 2 件
削除: 2026-07-01.log
削除: 2026-09-01.log
['2026-10-20.log', 'keep.txt']
新しいログと keep.txt は残りました。yes 以外なら「中止しました」と表示され、何も消えません。更新日時は stat() の st_mtime(1970 年からの秒数)で比べています。ポイントは、「探す」と「消す」を分けて先に一覧を見せること、dry_run の既定値を True にしてうっかり実行しても消えないようにすること、消す直前に対象が指定したフォルダーの中にあるかをもう一度確かめることの 3 つです。
フォルダーも消す対象にするなら、p.unlink() の代わりに shutil.rmtree(p) を使いますが、そのぶん一覧の確認をより慎重にしてください。Linux のコマンドで同じことをするなら「findコマンドの使い方」の -mtime(更新日時で探す)が参考になります。
ディスクの空き容量を調べる:disk_usage
大きなファイルをコピーする前に、空き容量を確かめたいときは disk_usage を使います。全体(total)・使用中(used)・空き(free)をバイト単位で返します。
import shutil
usage = shutil.disk_usage(".")
gb = 1024 ** 3
print(f"全体 {usage.total / gb:.1f} GB / 使用 {usage.used / gb:.1f} GB / 空き {usage.free / gb:.1f} GB")
全体 930.4 GB / 使用 565.7 GB / 空き 364.7 GB
“.” はカレントディレクトリのことで、そのフォルダーがあるドライブ(この例では C:)の容量が返ります。数字は PC ごとに違います。ここでは 1024 の 3 乗で割って GB(正確には GiB)にしています。
コマンドの場所を探す:which
which(コマンド名) は、環境変数 PATH をたどって、そのコマンドを実行したときに動くファイルのパスを返します。見つからなければ None です。PowerShell から実行しました。
import shutil
for cmd in ["py", "git", "python", "ls", "no-such-command"]:
print(f"{cmd:16} {shutil.which(cmd)}")
py C:\WINDOWS\py.EXE
git C:\Program Files\Git\cmd\git.EXE
python C:\Users\(ユーザー名)\AppData\Local\Microsoft\WindowsApps\python.EXE
ls None
no-such-command None
python の行は、実際には自分のユーザー名が入っていたので省略しています。拡張子が大文字の .EXE になっているのは、環境変数 PATHEXT(Windows で「拡張子なしで実行できる種類」の一覧。この PC では .COM;.EXE;.BAT;… と大文字)の書き方がそのまま使われるためです。
python が見つかった場所は WindowsApps の中で、これは Microsoft Store を開くための入口(0 バイトのファイル)でした。「python が動かないのに見つかる」ときは、which でどこが見つかっているかを確かめると原因が分かります。ls は PowerShell では「エイリアス」(Get-ChildItem の別名)でファイルではないので None ですが、Git Bash から同じコードを実行すると Git に付いてくる ls.EXE が見つかりました。起動したシェルによって PATH が変わるためです。
subprocess で外部コマンドを動かす前に if shutil.which("git") is None: と確かめておくと、「インストールされていません」と分かりやすいメッセージを出せます。PATH の仕組みは「環境変数PATHとは?」、外部コマンドの実行は「Pythonのsubprocessの使い方」で解説しています。
よくある間違い
| 症状 | 原因 | 直し方 |
|---|---|---|
| 拡張子なしのファイルができた | コピー先のフォルダー名を間違えた・まだなかった | 先に is_dir() で確かめる |
| バックアップに古いファイルが残り続ける | dirs_exist_ok=True は消したファイルを反映しない | コピー先を作り直すか、差分を自分で消す |
| move で大事なファイルが上書きされた | Windows でも移動先のファイルは上書きされる | move の前に exists() で確かめる |
| rmtree で PermissionError、一部だけ消えた | 読み取り専用のファイルがある(WinError 5)・ファイルを開いたままのプログラムがある(WinError 32) | onexc で読み取り専用を外す。開いているファイルを閉じてから消す |
よくある質問
フォルダーを ZIP にまとめるには?
shutil.make_archive を使うと 1 行で ZIP や .tar.gz を作れます。root_dir と base_dir の指定や zipfile との比べ方は「Pythonのzipfileの使い方」で説明しています。
pathlib だけでコピーできませんか?
Python 3.12 ではできません。公式ドキュメントによると、Python 3.14 で Path.copy()・copy_into()・move()・move_into() が追加されました。この記事は 3.12 で確かめているので、3.14 のメソッドの動きは試していません。3.13 以前でも動くコードにするなら shutil を使います。
まとめ
- ファイルのコピーは基本 copy2。コピー先がフォルダーかファイル名かで動きが変わる
- copytree は ignore_patterns で除外。dirs_exist_ok=True は上書きでミラーではない
- copy・move・copytree は確認なしで上書きすることがある
- rmtree はごみ箱に入らない。ドライランで一覧を確かめてから消す
関連する記事・ツール
- Pythonのpathlibの使い方|Pathでファイル・フォルダーを操作する方法と注意点
- Pythonのファイル読み書き|open・with・encoding指定と文字化けの直し方
- Pythonのzipfileの使い方|ZIPの作成・展開と圧縮・文字化け・安全な展開
- Pythonのsubprocessの使い方|外部コマンドの実行とshell=Trueの危険
- 環境変数PATHとは?Windows・Linuxの確認・設定と「認識されません」の直し方
- Pythonのglobとfnmatchでファイルを探す|**とrecursiveの注意点
- Pythonのtempfileの使い方|一時ファイル・フォルダーを安全に作って自動で消す