CodeFormerとは？

顔の復元・補完・高画質化に特化したAIツールです。
主に次のような用途に向いています

• ぼやけた顔写真を鮮明にしたいとき
• AI生成画像の崩れた顔（目・口・鼻）を修正したいとき
• ノイズが多い古い写真の顔を補完したいとき

CodeFormerの使用環境

CodeFormerやReal-ESRGAN、GFPGANのようなツールは、一般に以下のような環境を前提としています。

• Python（3.8～3.10あたり）
• PyTorch（＋CUDAドライバ：NVIDIAのGPUがあれば）
• Git
• LinuxまたはLinux系OS（Ubuntuなど）での動作

 しかし、これらの環境が無くても使用できる方法もあります。
今回は、上記の環境（ローカル）以外で使用できる方法を含めた、3通りの使用方法について、解説していきます。

使い方：3通りの方法

1⃣【手軽】ブラウザで試す（ローカルGPU不要）

Hugging Faceのデモページ

 Hugging Face CodeFormer ページはこちら

1. ページを開くと、シンプルな操作画面が出てくる
2. 画像をアップロードする（自分の写真や試したい画像）
3. 「Submit（送信）」ボタンを押す
4. 数秒〜1分くらい待つと、修復された顔画像が出てくる！
5. 完了したらダウンロード！

CodeFormer の各パラメータ解説

1. Pre Face Align（事前顔位置合わせ）

• 意味：顔画像を事前に「正面向き」に整える処理を行うかどうか。
• **有効（オン）**にすると：
  • 歪んだ顔、斜め向きの顔なども正面向きに近づけて修復できる
  • ただし、元の構図やアングルが崩れることもある
• オフにすると：
  • 元画像の向きそのままに処理される
• おすすめ：顔が大きく傾いている場合はオン、それ以外はオフでも可。

2. Background Enhance（背景強調）

• 意味：顔の修復と一緒に背景も補正・改善するかどうか。
• オンにすると：
  • 背景のボケやノイズも改善され、全体的に鮮明になることがある
• オフにすると：
  • 顔だけ修復され、背景には手を加えない
• 注意：顔だけ修復したい場合はオフのほうが自然です。

3. Face Upsample（顔の超解像処理）

• 意味：修復後に顔部分をさらに高解像度にアップスケールする機能。
• オンにすると：
  • 顔がよりシャープで詳細になる
• オフにすると：
  • アップスケールされないため元の解像度のまま
• おすすめ：最終的に大きく表示・印刷したい画像ではオン推奨。

4. Rescaling Factor（リスケーリング倍率）

• 意味：画像全体をどの倍率でアップスケールするかを指定（最大4倍）。
• 例：
  • 1.0 → 元の解像度のまま
  • 2.0 → 2倍サイズに拡大
  • 4.0 → 4倍サイズに拡大
• 注意：倍率を上げすぎると処理が重くなります。必要に応じて調整。

5. Codeformer Fidelity（忠実度）

• 意味：「元の顔にどれだけ似せるか」と「美化・修復」のバランスを指定。
• 数値の意味：
  • 0.0 → 品質重視（高品質、美化されやすいが元顔とはやや異なる）
  • 1.0 → 忠実度重視（元の顔に近くなるが、ノイズも残りやすい）
  • 0.5 → 中間（ほどよいバランス）
• おすすめ：
  • AIの美化を活かしたい → 0.0 ~ 0.3
  • 元の顔の特徴を重視したい → 0.7 ~ 1.0

注意事項

• 待ち時間があるかも（人気なので並ぶことがある）
• アップロードする画像サイズは小さめ（できれば512px以内）がスムーズ
• あくまで「デモ版」だから、商用利用はNG（正式に使いたいならローカルインストールかライセンスを確認）

 もうちょっと高機能版を使いたい場合や、自分のPCでCodeFormer動かしたい場合は2⃣へ！

※2⃣【やや中級者向け】Google Colabで使う（ブラウザ＋GPU）の、Google Colab以外の、恐らくGoogle Colab程メジャーではないけれど、最安値で、クラウドGPUがレンタルできるRunPodでStable Diffusioテンプレートを使用し、WebUI（ブラウザ）でCodeFormerを使用するという方法も、あります。
RunPodについては、 こちらの記事で解説しています。

あわせて読みたい

高性能クラウドGPUを使用できる”RunPod”はStable Diffusion学習の最適解！個人利用の効率よいクラウド環… Stable Diffusionで「思う存分、画像生成がしたい」「自分の作風を学習させたい」「LoRAやDreamBoothを試してみたい」と思ったら、まず課題になるのがGPUの性能や学習環…

2⃣ 【やや中級者向け】Google Colabで使う（ブラウザ＋GPU）

Step.1 Google Colabにアクセス

まず、Googleアカウントがあれば誰でも使える「Google Colab」にアクセスします。
  Google Colabはこちら

Step.2 新しいノートブックを作成

Colabを開いたら、

• 「ファイル」＞「ドライブの新しいノートブック」 をクリックして、新しいページを開きます。

Step.3 GPUを有効にする（これ超重要！）

CodeFormerは重いので、GPUを使う設定にしておきましょう！

1. メニューから「ランタイム」＞「ランタイムのタイプを変更」を選択
2. 「ハードウェアアクセラレータ」で「GPU」を選んで「保存」

これで、クラウド上のGPUが使える状態になりました！

Step.4 CodeFormerをColabにインストール・準備

コードは、一つのコードに対して一つのセルを使用します。
＋コードで、セルを追加して、コードを書きましょう。

① 必要なライブラリとCodeFormerをインストール

 次のコードを、Colabのセルにコピペして実行していきます！

# CodeFormer を GitHub からクローン
!git clone https://github.com/sczhou/CodeFormer.git
%cd CodeFormer

# 必要なパッケージをインストール
!pip install -r requirements.txt

# サブモジュールの取得（face parsingなど）
!git submodule update --init --recursive

 Ctrl＋Vでペースト出来ます。

 実行はセルの「▶️ボタン」を押します。

② CodeFormerの事前学習モデルをダウンロード

新しいセルを追加して、②の「事前学習モデルをダウンロードするコード」を貼り付けて、また実行します。

# 学習済みモデルをダウンロード（CodeFormer用）
!wget https://huggingface.co/lllyasviel/CodeFormer/resolve/main/codeformer.pth -O ./weights/CodeFormer/codeformer.pth

モデルが保存されると、復元処理ができるようになります。

（任意）セル③：画像復元を試す

# テスト画像で復元を試す（例：inputs/test.jpg）
!python inference_codeformer.py --w 0.7 --input_path ./inputs/test.jpg --bg_upsampler realesrgan

1セルにまとめて実行したい場合は、以下のようにしても動きます

!git clone https://github.com/sczhou/CodeFormer.git
%cd CodeFormer
!pip install -r requirements.txt
!git submodule update --init --recursive
!wget https://huggingface.co/lllyasviel/CodeFormer/resolve/main/codeformer.pth -O ./weights/CodeFormer/codeformer.pth

1つのセルにまとめてもOK
ディレクトリ移動（%cd）をまたぐ場合は注意
セルを 2つに分けた方がミスが起きにくくておすすめ！

git clone　GitHub から CodeFormer のコード一式を取得
pip install -r依存ライブラリ（Pythonパッケージ）をインストール
git submodule updateCodeFormer内部で使っている別リポジトリも取得（face parsingなど）
wget学習済みモデルファイル（.pth）を Hugging Face から取得
inference_codeformer.py画像を読み込み、顔の復元処理を実行するメインスクリプト

Step.5 画像をアップロードする

以下のコードをColabのセルに貼り付けて実行すると、画像をアップロードできます。

from google.colab import files
uploaded = files.upload()

 実行後、ファイル選択ダイアログが出るので、修復したい画像（顔写真など）を選んでください。

Step.5アップロード画像を CodeFormer のフォルダに移動

CodeFormerが読み込めるよう、画像を inputs フォルダに移動させます

import os
import shutil

# 画像ファイル名（アップロードした名前に合わせて変更）
filename = "my_photo.jpg"

# CodeFormerのinputsフォルダがなければ作成
os.makedirs("inputs", exist_ok=True)

# ファイルを移動
shutil.move(filename, f"inputs/{filename}")

Step.6 画像をCodeFormerで修復（復元）する

次に、アップロードした画像を修復するコードです 

# 復元実行（--w は復元の強さ、1.0=完全復元、0.7くらいが自然）
!python inference_codeformer.py --w 0.7 --input_path inputs/my_photo.jpg --bg_upsampler realesrgan

⚠ my_photo.jpg は、アップロードしたファイル名に合わせて変更してください。

これで、アップロードした顔画像が補完・修復された状態で出てきます！
結果画像を表示するコード （オプション）

from IPython.display import Image, display

# 出力画像のパス（復元結果は results ディレクトリに保存される）
output_path = "results/final_results/my_photo.jpg"

# 表示
display(Image(output_path))

この処理は、すでに以下が完了している前提です

• CodeFormerのクローンとインストール
• モデルファイル（codeformer.pth）のダウンロード済み
• Colabのカレントディレクトリが CodeFormer にある

もしそれが途中になっていたら、再度まとめて整えることもできます！

files.upload()で画像をアップロード
inputs/に移動
inference_codeformer.pyで修復
results/から表示

Step7 完成した画像をダウンロードする

最後に、出力画像（output.png）をダウンロードして保存できます！

files.download('output.png')

※無料でGPUが使えるのが魅力！重い画像も快適処理。

google colabでエラーが出て使えない時と、Colab の無償枠で GPU 上限に達してしまったときの代替手段については、 こちらの記事をご覧ください。

Sakasa AI

Google Colab エラー時の ランタイムリセット と ランタイム復旧【CodeFormerが使えない時】 | Sakasa AI Google Colabいくつかのエラーとランタイムの復旧 当記事は下記ページ【CodeFormerの使い方】のスポットライト記事として書いたものです。”Google Colab の使用方法”につい…

あわせて読みたい

Colab の無料枠制限で GPU 上限に達した場合の”回復までの時間”と”代替手段” 回復までの時間 Google Colab 無料枠の GPU 使用上限は時間が経つと回復します。ただし、その「回復までの時間」や「どれくらい使えるか」はユーザーごとに異なり、以下…

「CodeFormerを動かす為のまとめノートブック」を作る手順

同じ操作を繰り返したい場合は、まとめノートブックを作成しておくと 実行ボタンのみを押すだけで、簡単に同じ操作を繰り返す事が出来ます。
作成方法は以下の通りです。

【STEP 1】新しいGoogle Colabノートブックを開こう！

まずは、

• Google Colab にアクセス
• 画面左上の「ファイル > 新しいノートブック」をクリック

すると、新しい空っぽのノートブックが開きます。
（名前は後でつければOKです）

順番にセルを作っていきましょう！

【STEP 2】最初のセルに書くコード

まずは「CodeFormerのソースコードをGitHubからダウンロード」してきます。

ノートブックの一番上のセルに、次のコードをコピペしてください 

# CodeFormerをクローン
!git clone https://github.com/sczhou/CodeFormer.git

# CodeFormerフォルダに移動
%cd CodeFormer

# 必要なライブラリをインストール
!pip install -r requirements.txt

# さらに必要な依存ライブラリもインストール
!pip install -q basicsr facexlib gfpgan
!pip install -q -U openmim
!mim install -q mmcv-full

左側の「▶️ボタン（セルを実行）」を押してください！

【STEP 3】事前学習モデル（重みファイル）をダウンロードするセル

次は、CodeFormerの学習済みモデル（codeformer.pth）をダウンロードするコードを書きます。

新しいセルを追加して、次をコピペしてください 

# 重みファイルを保存するフォルダを作成
!mkdir -p weights

# CodeFormerの学習済みモデルをダウンロード
!wget -P weights https://github.com/sczhou/CodeFormer/releases/download/v0.1.0/codeformer.pth

【ポイント】

• weights というフォルダを作って、そこに保存します。
• この「重み」がないと、顔修復ができないので必須です！

【やること】

1. 新しいセルを追加して
2. 上のコードを貼り付けて
3. 「▶️」ボタンで実行！

ダウンロードする「学習済みモデル（codeformer.pth）」のサイズがけっこう大きい（数百MB以上ある）為、時間が掛かる場合があります。ColabのサーバーとGitHubの通信速度はそのときの回線状況に左右されます。

【目安時間】

• 早いとき ➔ 10秒〜30秒くらい
• 遅いとき ➔ 数分かかることもある

なので、のんびり待っていればOKです。
（途中でエラーが出なければ問題なし！）

【もし途中でエラーになったら？】

もし仮にダウンロード中にエラーが出ても、
もう一度「セルの▶️ボタンを押して再実行」すれば大丈夫です！

【STEP 4】画像をアップロードするセルを作ります！

Colab上に、CodeFormerで直したい自分の画像ファイルをアップロードする仕組みを作りましょう！
次のコードを新しいセルにコピペしてください 

from google.colab import files

# ファイルアップロード
uploaded = files.upload()

1. 上のコードを貼り付けて
2. ▶️ボタンを押します

すると、「ファイルを選んでください」というウィンドウが出るので、
手元にある顔画像ファイルを選んでアップロードしてみてください

【STEP 5】CodeFormerで画像補正を実行するセル

次のコードを、新しいセルに貼り付けてください 

# 推論に必要なモジュールをインポート
import torch
from torchvision.utils import save_image
from basicsr.archs.codeformer_arch import CodeFormer
from torchvision import transforms
from PIL import Image
import os

# CodeFormerモデルの準備
net = CodeFormer(dim_embd=512, codebook_size=1024, n_heads=8, n_layers=9, connect_list=["32", "64", "128", "256"])
ckpt_path = 'weights/codeformer.pth'
net.load_state_dict(torch.load(ckpt_path)['params_ema'])
net = net.eval().cuda()

# アップロードしたファイル名を取得
filename = list(uploaded.keys())[0]

# 画像の読み込みと前処理
img = Image.open(filename).convert("RGB")
transform = transforms.Compose([
    transforms.Resize((512, 512)),
    transforms.ToTensor()
])
img_input = transform(img).unsqueeze(0).cuda()

# 顔補正を実行
with torch.no_grad():
    output = net(img_input, w=0.7, adain=True)[0]
    output = (output.clamp(-1, 1) + 1) / 2

# 結果を保存
save_image(output, 'restored_image.png')

# 画像を表示
from IPython.display import Image as IPImage, display
display(IPImage('restored_image.png'))

CodeFormerモデルをロードしてアップロードした画像を読み込んで顔をきれいに復元（補正）して結果を表示＆保存する

【注意点】

保存されたファイル名は restored_image.png になります！
最初にアップロードした画像ファイル名が自動で使われます。

 このようなエラーが出た場合

ModuleNotFoundError: No module named 'basicsr'

次のコマンドを新しいセルにコピペして、実行してください 

!pip install basicsr

これでbasicsrがインストールされます！
（この作業は、Colabを新しく開いたときは毎回やる必要があります）インストールが終了したら、一度画面左上のランタイムのタブをクリックして、セッションを再起動をして下さい。

 このようなエラーが出た場合

ModuleNotFoundError: No module named 'torchvision.transforms.functional_tensor'

これは、今インストールされてる「torchvision」のバージョンが低すぎて、必要な機能がない場合のエラーです。

次のコマンドを新しいセルにコピペして、実行してください 

!pip install torchvision --upgrade

これで、最新の torchvision にアップデートできます。

3⃣【上級者向け】ローカルPCに導入して使う方

CodeFormerをローカルで使うためのPC環境

1. 【OS環境】

• 対応OS
  • Windows 10 / 11
  • macOS（Intel or Apple Silicon）
  • Linux（Ubuntu推奨）

※ただし、GPU処理（高速動作）したい場合はWindows or Linuxを強く推奨。

2. 【Python・CUDA環境】

3. 【PCスペック】

GPUはCUDA対応のNVIDIA製が必須です。AMDやIntel GPUは非対応です。

AIツールに適したGPUの選び方

画像生成のためのGPU選び”今話題のRTX 5060は？””RTX3060でも大丈夫？”おすすめGPUと各種比較 画像生成AIを使いたい！GPUは何を選べばいい？ Stable DiffusionやComfyUIで画像生成に挑戦したい――そう思ったとき、最初に立ちはだかる壁が「GPU選び」ではないでしょ…

4. 【その他の条件】

• Python環境は仮想環境（venv）で構築するのがおすすめ Python 3.10.6 をインストールすれば、基本的にvenvも自動で入ります
• Pythonライブラリの依存関係を pip install -r requirements.txt で管理
• インターネット接続（初回はモデルファイルなどをダウンロードするため）

GPUがないとどうなる？

• CPUでも動作はしますが「1枚の画像処理に数分〜十数分かかる」こともあります。
• GPUがあると「数秒〜十数秒で処理完了」なので、作業効率が段違いです。

手順

1. CodeFormerのソースコードをGitHubから取得 Git公式サイト
   まずは公式GitHubリポジトリをクローンします

git clone https://github.com/sczhou/CodeFormer.git
cd CodeFormer

2.仮想環境（venv）を推奨

python -m venv codeformer-env
source codeformer-env/bin/activate      # macOS/Linux
codeformer-env\Scripts\activate         # Windows

macOS/Linuxは、1，2段目を使用してください。
Windowsの方は、１,３段目のコマンドを使用してくださいね。

3、依存パッケージのインストール
以下で、必要なPythonライブラリをまとめてインストールします。

pip install -r requirements.txt

このコマンドは、requirements.txt に書かれている依存ライブラリ（例：torch, opencv-pythonなど）を一括でインストールします。
もし依存関係でエラーが出る場合は、torch を手動でインストールすることもあります

pip install torch torchvision torchaudio

※ GPU を使うなら、PyTorch の公式サイト（https://pytorch.org/get-started/locally/）で適切なバージョンを選んでインストールしましょう。

  PyTorch（AIフレームワーク）を自分のPC環境に合った形でインストールするためのコマンドについて,
以下の記事で詳しく解説していますので、ご覧ください。

Sakasa AI

ローカルCLI（Pythonスクリプト）の為の【PyTorch＋CUDA】のインストール手順 | Sakasa AI PyTorch + CUDA のインストール GPUとCUDAの互換性確認 GPUとCUDAの互換性を確認するには、以下の3つのステップで簡単にチェックできます。これは、PyTorch・Stable Diffus…

4,事前学習済みモデル（CodeFormer.pth）を以下のURLから CodeFormer.pth をダウンロード
 https://github.com/sczhou/CodeFormer/releases

GitHubの公式リポジトリの「README」にあるURLから、weights フォルダに保存します。

以下のように配置します。

CodeFormer/
└── weights/
    └── CodeFormer.pth

weights/CodeFormer.pth というファイルパスになるように置いてください。

 ダウンロード後のファイル配置の仕方
ダウンロードした CodeFormer.pth を、現在の作業ディレクトリ（例：CodeFormer フォルダ内）に置いておく方法です。
例 Windows（PowerShellやコマンドプロンプト）の場合

mkdir weights\CodeFormer
move CodeFormer.pth weights\CodeFormer\

例（Linux/macOSの場合）

mkdir -p weights/CodeFormer
mv CodeFormer.pth weights/CodeFormer/

このコマンドによりweights/CodeFormer/CodeFormer.pth という必要なパスにモデルファイルが移動します。

 なぜこの場所に配置する必要があるのか？
inference_codeformer.py やその他のスクリプト内で

os.path.join('weights/CodeFormer', 'CodeFormer.pth')

といったように、決められた場所からモデルを読み込む設計になっているからです。

テスト画像で動作確認

例として、画像 input.jpg を補正してみます。

python inference_codeformer.py -w 1.0 --input_path ./inputs/input.jpg --face_upsample

解説

• -w 1.0: 再構成の重み（0〜1。1は構造重視、0は画質重視）数値が大きいほど「顔の再構成を強めに」行う（=リアルさ重視）
• --input_path: 入力ファイルまたはフォルダのパス
  画像1枚なら xxx.jpg、フォルダ指定も可能（複数処理）
• --face_upsample: 顔だけでなく背景も一緒に超解像したい場合に指定（任意）
• --bg_upsampler: Real-ESRGAN などの背景用アップサンプラー（オプション)
• --output_path:出力先のパス（省略可。デフォルトは results/ フォルダ）

例：画像1枚を処理する場合

画像構成（例）

CodeFormer/
├── inference_codeformer.py
├── inputs/
│   └── face.jpg
├── weights/
│   └── CodeFormer/
│       └── CodeFormer.pth

実行コマンド:

python inference_codeformer.py -w 1.0 --input_path inputs/face.jpg --face_upsample --output_path outputs/

この例では:

• inputs/face.jpg を処理
• 結果が outputs/ フォルダに保存される（自動で作成される）

フォルダごと一括処理する場合

python inference_codeformer.py -w 1.0 --input_path inputs/ --face_upsample --output_path outputs/

inputs/ 内にある全画像（JPG, PNG）を一括処理して、outputs/ に出力します。

出力ファイルについて

実行後、指定した --output_path に以下のようなファイルが生成されます

• final_results: 修復後の最終画像（背景込み）
• restored_faces: 修復された顔の部分（切り出し）

補足オプション（任意）

注意点
ファイル名に日本語や全角文字があると処理に失敗する場合があります。
複数画像の一括処理では、画像形式は .jpg, .png などが対応（.webp などは注意）。

おまけ：Web UIで試す方法

CodeFormer には簡易Web UI（gradio）も用意されています

python basicsr/tools/webcam_demo.py

※ gradio を追加でインストールする必要があります

pip install gradio

実行！画像を指定して処理を開始

例：

python inference_codeformer.py --w 0.7 --input_path inputs/test.jpg --output_path results/

--w パラメータは「どれくらいAI補正するか（0〜1）」を指定します。0に近いと原画寄り、1に近いと修正が強くなります。
出力結果は results/ フォルダに保存されます。
GPU環境があれば高速ですが、CPUでも動作は可能です（ただし時間がかかります）。

おすすめ設定とコツ

どんな画像に向いてる？

イラストよりは「写真風」向き（リアル寄りの顔）
AI画像で顔が「崩れがち」なときの補修に最適
特に「顔だけ浮いてる画像」や「古い写真」が得意分野です！

顔だけなの？

CodeFormerは 全体の画像ではなく「顔部分のみ」に特化 しています。
顔以外の補完は別のツール（例：Real-ESRGANなど）と組み合わせるのがおすすめです。

あわせて読みたい

Real-ESRGAN と GFPGANを連携させる方法とGUIで使えるツール Real-ESRGAN と GFPGAN インストール手順や使い方においても Real-ESRGAN（リアル・イーエスアールガン）と GFPGAN （ジーエフピーガン）はかなり似ています。両方とも …

あわせて読みたい

GFPGANのインストール方法 GFPGANとは？ GFPGANは、AIの顔修復モデルとして一時期バズりましたが、**「実物と全然違う顔になる」**というある意味での“炎上”も経験しました。ネットでは「GFPGANが…