Python
PR

Pythonのshutilの使い方|ファイル・フォルダーのコピー・移動・削除と注意点

Pythonのshutilの使い方|ファイル・フォルダーのコピー・移動・削除と注意点
hr
記事内に商品プロモーションを含む場合があります

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 です。

左の pathlib はパスの組み立て、存在の確認と一覧、1 ファイルの読み書き、名前の変更と 1 つの削除を担当。右の shutil はファイルのコピー、フォルダーごとのコピー、移動、中身ごとの削除を担当。Path はそのまま shutil に渡せる。ほかに disk_usage と which がある
図 1: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)ないフォルダーの名前の最後に / を付けた同上。フォルダーを作ってから渡す
PermissionErrorcopyfile のコピー先にフォルダーを書いた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 はごみ箱に入らない。ドライランで一覧を確かめてから消す

関連する記事・ツール

ABOUT ME
hr
hr
エンジニアとして働いている hr です。仕事や資格勉強で「こんなツールがあれば」と感じたものを、無料Webツールと解説記事にして発信しています。
記事URLをコピーしました