Gradioとは｜使い方・API呼び出し・Spaces公開をPythonで実演

関数を部品（入力欄・出力欄）で包み、launch() すると、画面とAPIが同時にできます。

flowchart TD
    A[Pythonの関数] --> B[Interface・Blocks<br>ChatInterface]
    B --> C[launch]
    C --> D[画面]
    C --> E[API<br>client・curl]
    C --> F[公開<br>share・Spaces]

やりたいことごとの書き方です。

確認環境：Ubuntu 24.04・Python 3.11.15・Gradio 6.30.0（2026年10月8日公開の PyPI 最新版）・gradio_client 2.7.2・FastAPI 0.143.3・Streamlit 1.66.0・Chromium（Playwright で操作）。venv に pip で入れ、この記事のアプリをすべて起動して、ブラウザでの操作結果・gradio_client と curl の応答・エラー文を確かめています。share・Spaces・OAuth・環境変数は Gradio 公式ガイド（GitHub の guides）、Spaces の条件と料金は Hugging Face の公式ドキュメントと料金ページ、Streamlit の実行モデルは Streamlit の公式ドキュメントで確かめました（確認日 2026年10月17日）。

Gradioとは

Gradio（グラディオ）は、機械学習のモデルや API、ふつうの Python の関数に、Web の画面を付けるオープンソースの Python ライブラリです。 公式のクイックスタートは「JavaScript・CSS・Web ホスティングの経験は要らない」と説明しています。公式は、Gradio アプリを置く場所として最もよく使われているのが Hugging Face Spaces だと紹介しています。

Gradioでできること

• 関数の入力と出力に部品を割り当てるだけで、入力欄・ボタン・出力欄のある画面ができる
• 画像・音声・動画・表・グラフ・チャットの部品が最初から入っている
• 画面と同時に API が自動でできる。Python（gradio_client）・JavaScript（@gradio/client）・curl から呼べる
• share=True で、手元の PC で動かしたまま外部から見られる URL を発行できる
• Hugging Face Spaces に置くと、URL を固定して公開できる
• mcp_server=True で、関数を MCP（AI エージェントが外部の道具を呼ぶための規格）のツールとして公開できる

画面の作り方は3種類

Gradioのインストール（pip・venv）

公式は、仮想環境（venv）に pip で入れる形を勧めています。

python3 -m venv .venv
source .venv/bin/activate        # Windows は .venv\Scripts\activate
pip install --upgrade gradio
python -c "import gradio; print(gradio.__version__)"

6.30.0

依存も含めて、venv 全体の大きさは 494MB でした（Linux・Python 3.11 で gradio だけを入れた場合）。venv の作り方は、関連記事「Python venvの使い方｜仮想環境の作成・有効化・削除をOS別にコピペ」で扱っています。uv を使うときは uv add gradio です。関連記事「uvの使い方｜pip・venvからの移行とチーム開発での使い方」で扱っています。

入った版と依存を確かめる（gradio environment）

gradio environment

Gradio Environment Information:
------------------------------
Operating System: Linux
gradio version: 6.30.0
gradio_client version: 2.7.2

------------------------------------------------
gradio dependencies in your environment:

anyio: 4.15.1
audioop-lts is not installed.
brotli: 1.2.0
fastapi: 0.143.3
gradio-client: 2.7.2
...

Python 3.9 では Gradio 4 系が入る

Python 3.9 以下で pip install gradio を実行すると、エラーにならずに Gradio 4.44.1 が入ります。 Gradio 5.0.0 以降は Python 3.10 以上が条件だからです。Python 3.9 向けに版を指定して取得すると、次のように止まりました。

ERROR: Ignored the following versions that require a different python version: 5.0.0 Requires-Python >=3.10; ... 6.30.0 Requires-Python >=3.10; ...
ERROR: No matching distribution found for gradio==6.30.0

4 系と 6 系では書き方が違う所が多いので、ネットの記事のコードが動かないときは、まず python --version と gradio.__version__ を確かめます。

Gradioの使い方① Interface（最小コード）

公式のクイックスタートと同じ形の、名前と回数を受け取ってあいさつを返すアプリです。

# interface_app.py
import gradio as gr

def greet(name, intensity):
    return "Hello, " + name + "!" * int(intensity)

demo = gr.Interface(
    fn=greet,
    inputs=["text", "slider"],
    outputs=["text"],
)

demo.launch(server_port=26301)   # 省略すると 7860 番

python interface_app.py

* Running on local URL:  http://127.0.0.1:26301
* To create a public link, set `share=True` in `launch()`.

ブラウザで開き、Playwright で操作して確かめた結果です。

inputs の部品の数は関数の引数の数に、outputs の数は戻り値の数に合わせます。 "text" のような文字列でも、gr.Textbox(label="名前") のようなインスタンスでも指定できます。インスタンスにすると、ラベル・初期値・範囲などを細かく決められます。

demo = gr.Interface(
    fn=greet,
    inputs=[gr.Textbox(label="名前"), gr.Slider(1, 10, value=3, step=1, label="回数")],
    outputs=gr.Textbox(label="あいさつ"),
    title="あいさつ",
    examples=[["RJC", 3], ["Gradio", 5]],
)

よく使う部品

gr.Image(type="pil") で受け取った画像は、Pillow の関数でそのまま加工できます。

保存するたびに再読み込みする（ホットリロード）

python の代わりに gradio コマンドで起動すると、ファイルを保存するたびにアプリが読み込み直されます。

gradio reload_app.py

返事の頭を v1: から v2: に書き換えて保存したときのログです。止めずに API を呼ぶと、v2: x が返りました。

Watching: '…/app'

Watching demo: demo
* Running on local URL:  http://127.0.0.1:26307
* To create a public link, set `share=True` in `launch()`.
Changes detected in: …/app/reload_app.py

ホットリロードは、ファイルの中の demo という名前の変数を探します。別の名前にしたときは gradio app.py --demo-name 変数名 と指定します。

Gradioの使い方② Blocks（レイアウトとイベント）

Blocks では、with の中に部品を並べ、ボタンなどのイベントに関数を結びます。足し算と文字数を数える2つの処理を持つアプリです。

# blocks_app.py
import gradio as gr

def add(a, b):
    if a is None or b is None:
        raise gr.Error("数値を2つ入れてください")
    return a + b

def count_chars(text):
    return len(text), text.upper()

with gr.Blocks(title="Blocks の例") as demo:
    gr.Markdown("## 足し算と文字数")
    with gr.Row():                       # 横に並べる
        a = gr.Number(label="a")
        b = gr.Number(label="b")
    total = gr.Number(label="a + b")
    gr.Button("足す").click(add, inputs=[a, b], outputs=total, api_name="add")
    with gr.Tab("文字数"):               # タブ
        t = gr.Textbox(label="文章")
        n = gr.Number(label="文字数")
        up = gr.Textbox(label="大文字")
        t.change(count_chars, inputs=t, outputs=[n, up], api_name="count")

demo.launch(server_port=26302)

ブラウザで a に 12、b に 30 を入れて「足す」を押すと、a + b の欄に 42 が出ました。a を空にして押すと、画面の右上に「Error」の通知が出て、gr.Error に渡した「数値を2つ入れてください」が表示されました。

関数の戻り値をタプルで返すと、outputs のリストの順に入ります。 上の count_chars は、文字数と大文字の2つの欄を一度に更新しています。

Gradio 6 で変わった書き方

以前の版の記事のコードを 6.30.0 で動かすと、次のように止まります。どれも手元で出た原文です。

Gradioの使い方③ ChatInterface（チャットボット）

gr.ChatInterface に渡す関数は、最新のメッセージ（message）と、それまでの履歴（history）をこの順に受け取ります。 yield で少しずつ返すと、文字が流れるように表示されます（ストリーミング）。

# chat_app.py
import time
import gradio as gr

def slow_echo(message, history):
    turns = len([h for h in history if h["role"] == "assistant"])
    reply = f"{turns + 1}回目の返事：{message}"
    for i in range(len(reply)):
        time.sleep(0.05)
        yield reply[: i + 1]

gr.ChatInterface(fn=slow_echo, title="エコーボット").launch(server_port=26303)

ブラウザで「こんにちは」「Gradio」と続けて送ると、1回目の返事：こんにちは、2回目の返事：Gradio と返りました。2回目は履歴に1回目の返事が入っているため、数が増えています。

history の中身（Gradio 6）

関数に届いた history を print した結果です。content は文字列ではなく、type と text を持つ辞書のリストです。

HISTORY []
HISTORY [{'role': 'user', 'metadata': None, 'content': [{'text': '一つ目', 'type': 'text'}], 'options': None}, {'role': 'assistant', 'metadata': None, 'content': [{'text': 'ok:一つ目', 'type': 'text'}], 'options': None}]

h["content"] を文字列として扱うコードは、この形に合わせて h["content"][0]["text"] のように取り出します。role が user・assistant なので、LLM の API に渡すメッセージの形に近い構造です。

OpenAI 互換の API を持つサーバー（Ollama など）があれば、公式ガイドにある gr.load_chat で1行でチャット画面を作れます（pip install openai が要ります）。

import gradio as gr
gr.load_chat("http://localhost:11434/v1/", model="llama3.2", token="***").launch()

fn の中で LLM の API を呼ぶ書き方は、関連記事「Claude API Python入門｜Anthropic SDKコピペレシピ集」で扱っています。検索した文書を使って答えさせる形は、関連記事「RAGの作り方｜Pythonで動かす最小構成と精度の上げ方」で扱っています。

GradioをAPIとして呼ぶ（gradio_client・curl）

Gradio のアプリは、起動した時点で API にもなっています。 画面の下の「Use via API」から、呼び方の説明ページが開きます。

API の名前は関数名になる

Gradio 6.30.0 では、API の名前（api_name）を省略すると関数名がそのまま使われます。 ネットでよく見る api_name="/predict" で呼ぶと、次のエラーになりました。

ValueError: Cannot find a function with `api_name`: /predict.

名前は view_api() で確かめられます。

gradio_client（Python）で呼ぶ

gradio_client は gradio を入れると一緒に入ります。呼ぶ側だけなら pip install gradio_client で入ります。

from gradio_client import Client

c = Client("http://127.0.0.1:26301/")
c.view_api()
print(c.predict(name="RJC", intensity=3, api_name="/greet"))

b = Client("http://127.0.0.1:26302/", verbose=False)
print(b.predict(12, 30, api_name="/add"))
print(b.predict("gradio", api_name="/count"))
try:
    b.predict(None, 30, api_name="/add")
except Exception as e:
    print(type(e).__module__ + "." + type(e).__name__, ":", e)

Loaded as API: http://127.0.0.1:26301/
Client.predict() Usage Info
---------------------------
Named API endpoints: 1

 - predict(name, intensity, api_name="/greet") -> output
    Parameters:
     - [Textbox] name: str (required)  
     - [Slider] intensity: float (not required, defaults to:   0)  
    Returns:
     - [Textbox] output: str 

Hello, RJC!!!
42
(6, 'GRADIO')
gradio_client.exceptions.AppError : 数値を2つ入れてください

• 出力が2つ以上ある処理（/count）は、タプルで返る
• gr.Error で止めた処理は、AppError として同じ文が届く

ストリーミングするチャットは、submit() で受け取ると途中の結果も取れます。

ch = Client("http://127.0.0.1:26303/", verbose=False)
job = ch.submit("こんにちは", api_name="/slow_echo")
outs = list(job)
print(len(outs), "partial outputs; first:", repr(outs[0]), "last:", repr(outs[-1]))
print("result:", job.result())

12 partial outputs; first: '1' last: '1回目の返事：こんにちは'
result: 1回目の返事：こんにちは

12文字の返事が、1文字ずつ12回に分かれて届きました。API で呼ぶと履歴は空から始まるため、何回呼んでも「1回目」です。

curl で呼ぶ（POST と GET の2回）

curl では、POST で処理を頼んで event_id を受け取り、GET でその結果を受け取る、の2段階です。Gradio 6.30.0 では URL の前に /gradio_api が付きます。

curl -X POST http://127.0.0.1:26301/gradio_api/call/greet \
  -H "Content-Type: application/json" -d '{"data": ["RJC", 3]}'

{"event_id":"2874bd929b2d4fd081408406aba8c861"}

curl -N http://127.0.0.1:26301/gradio_api/call/greet/2874bd929b2d4fd081408406aba8c861

event: complete
data: ["Hello, RJC!!!"]

data には、入力の部品の順に値を並べます。結果は SSE（Server-Sent Events。サーバーから続けて送る形式）で届き、ストリーミングのチャットでは途中の結果が event: generating として続きます。

event: generating
data: ["1", null]

event: generating
data: ["1回", null]

API の一覧は GET /gradio_api/info で JSON として取れます。中には Python・JavaScript・curl の呼び出し例（code_snippets）も入っていました。

既存の FastAPI に組み込む

すでに FastAPI のアプリがあるときは、gr.mount_gradio_app で好きなパスの下に置けます。

from fastapi import FastAPI
import gradio as gr
import uvicorn

app = FastAPI()

@app.get("/health")
def health():
    return {"status": "ok"}

demo = gr.Interface(lambda s: s[::-1], "text", "text", api_name="reverse")
app = gr.mount_gradio_app(app, demo, path="/gradio")

if __name__ == "__main__":
    uvicorn.run(app, host="127.0.0.1", port=26308)

$ curl http://127.0.0.1:26308/health
{"status":"ok"}
$ curl -o /dev/null -w '%{http_code}\n' http://127.0.0.1:26308/gradio/
200
（/gradio/gradio_api/call/reverse に "Gradio" を送ると）
event: complete
data: ["oidarG"]

FastAPI 自体の書き方は、関連記事「FastAPI入門｜uvで作るCRUD API完成コードと実行結果」で扱っています。

Gradioの公開・認証・キュー

share=True：一時的な公開 URL

demo.launch(share=True)

公式ガイドでは、https://07ff8706ab.gradio.live のような URL が発行され、リンクは1週間で失効します。Gradio の share サーバーは手元のサーバーへの中継だけで、送られたデータを保存しないと書かれています。一方で、URL を知っている人は誰でも使えるため、認証と組み合わせることが勧められています。

share は frpc という中継用のプログラムをダウンロードして使います。外部への接続が制限された環境では、エラーで止まらずに次の文が出て、手元の URL だけで起動しました。

Could not create share link. Missing file: ~/.cache/huggingface/gradio/frpc/frpc_linux_amd64_v0.3. 

Please check your internet connection. This can happen if your antivirus software blocks the download of this file. You can install manually by following these steps: 

1. Download this file: https://cdn-media.huggingface.co/frpc-gradio-0.3/frpc_linux_amd64
2. Rename the downloaded file to: frpc_linux_amd64_v0.3
3. Move the file to this location: ~/.cache/huggingface/gradio/frpc

会社のネットワークでこの文が出たときは、プロキシやセキュリティ製品が huggingface.co への接続を止めていないかを確かめます。社外へ出さずに同じ LAN の人に見せたいときは、server_name="0.0.0.0" で起動します（既定は 127.0.0.1 で、自分の PC からしか開けません）。

auth：パスワード認証

import gradio as gr

def whoami(request: gr.Request):
    return f"ログイン中：{request.username}"

with gr.Blocks() as demo:
    m = gr.Markdown()
    gr.Button("ログアウト", link="/logout")
    demo.load(whoami, None, m)

demo.launch(auth=[("admin", "pass1234"), ("guest", "guest5678")])

起動すると、画面の前に「username」「password」「Login」だけのログイン画面が出ます。curl と gradio_client で確かめた結果です。

auth には、ユーザー名とパスワードを受け取って True・False を返す関数も渡せます。公式ガイドは、組み込みの認証は基本的なアクセス制限で、多要素認証・回数制限・ロックアウトのような機能は無いと書いています。Hugging Face のアカウントでログインさせる gr.LoginButton（Spaces で hf_oauth: true）や、FastAPI に組み込んで Google などの OAuth を使う方法もあります。

キュー：同時に処理する数

Gradio のイベントは、既定で1件ずつ順番に処理されます（concurrency_limit の既定は 1）。 2秒かかる関数に、3件の依頼を同時に送って比べました。

import time
import gradio as gr

def slow_a(x):
    time.sleep(2)
    return x

def slow_b(x):
    time.sleep(2)
    return x

with gr.Blocks() as demo:
    i = gr.Textbox(); o1 = gr.Textbox(); o2 = gr.Textbox()
    gr.Button("既定").click(slow_a, i, o1, api_name="default_limit")
    gr.Button("3並列").click(slow_b, i, o2, api_name="limit3", concurrency_limit=3)

demo.queue(max_size=20).launch()

同じ関数を2つのボタンに結ぶと、キューも1つにまとまります。 最初は1つの関数 slow を両方のボタンに結んでいたため、concurrency_limit=3 の側も 6.1 秒かかりました。ソースでは、concurrency_id を指定しないと関数ごとに ID が決まり、同じ ID のイベントは小さい方の上限に従います。別々に並列にしたいときは、関数を分けるか、concurrency_id を明示します。

外部の API を呼ぶだけの関数のように、同時に動かしても問題が無い処理は concurrency_limit=None にできます。GPU を使う処理は、GPU の数に合わせて concurrency_id で上限を共有させる形が公式ガイドの例です。

よく使う launch() の引数と環境変数

GRADIO_ANALYTICS_ENABLED は、Gradio の利用状況（動かしている環境・使っている部品など）を Gradio 側へ送る設定です。公式ガイドでは、アプリを使う人の情報は送らないと書かれています。止めるときは GRADIO_ANALYTICS_ENABLED=False です。

Hugging Face Spacesに公開する手順

Hugging Face Spaces は、Gradio のアプリを URL を固定して公開できる Hugging Face のホスティングです。 ただし、2026年10月17日時点の公式ドキュメントでは、Gradio と Docker の Space は計算資源を使うため、作成に有料プラン（個人は PRO、組織は Team か Enterprise）が要ると書かれています。無料の個人アカウントは、ZeroGPU 上で動く Gradio の Space を2つまで置けます。

README.md の先頭は、たとえば次の形です。

---
title: Greeting Demo
sdk: gradio
sdk_version: 6.30.0
app_file: app.py
python_version: "3.11"
---

gradio deploy --help の出力です。6.30.0 では、Spaces のほか Google Cloud Run も選べます。

 Usage: gradio deploy [OPTIONS]                                                 

 Deploy a Gradio app to Spaces or Google Cloud Run. Must be called within the   
 directory you would like to deploy.                                            

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --title           <str>  Spaces app title                                    │
│ --app-file        <str>  File containing the Gradio app                      │
│ --provider        <str>  Deployment provider (spaces or gcloud)              │
│                          [default: spaces]                                   │
│ --help                   Show this message and exit.                         │
╰──────────────────────────────────────────────────────────────────────────────╯

公開した Space の Gradio アプリは、https://ユーザー名-space名.hf.space の URL で開け、gradio_client や curl からも同じように呼べます。非公開の Space を呼ぶときは、Authorization: Bearer $HF_TOKEN のヘッダー（gradio_client では token=）を付けます。

GradioとStreamlitの違い

どちらも Python だけで Web の画面を作るライブラリです。大きな違いは、操作されたときに何が動くかです。同じ「名前を入れてあいさつを返す」アプリで、入力を3回変えたときの実行回数を数えました。

Streamlit の公式ドキュメントにも、画面を更新する必要があるたびに Python のスクリプト全体を上から再実行する、と書かれています。

どちらを選ぶかの判断表

Gradioでよくあるエラーと直し方

この記事のアプリを動かしたときに、実際に出た文です。

ポートが使われているときの調べ方は、関連記事「Address already in useの解決方法【Windows・Mac・Linux】」で扱っています。

画面が開けないときの確かめ方

• 別の PC から開けない：既定は 127.0.0.1 で待ち受けるため。server_name="0.0.0.0" か GRADIO_SERVER_NAME=0.0.0.0 にする
• ログインしても画面に戻される：公式ガイドでは、認証には Cookie が要り、Safari や Chrome のシークレットモードの既定の設定では動かないことがあると書かれている
• nginx の配下（/app/ など）に置くと画面が崩れる：root_path か GRADIO_ROOT_PATH に、そのパスを指定する
• 画面は動くのに API が呼べない：/gradio_api を付け忘れている（付けないと 404）

よくある質問

Q. Gradioとは何ですか？ A. Python の関数に、数行で Web の画面と API を付けるオープンソースのライブラリです。機械学習のモデルや LLM のデモ、社内向けの小さな道具に使われます。「Gradioとは」の節に、できることと3種類の作り方をまとめています。

Q. Gradioの使い方は？ A. pip install gradio で入れ、gr.Interface(fn=関数, inputs=..., outputs=...) を作って launch() します。ブラウザで http://127.0.0.1:7860 を開くと画面が出ます。Interface・Blocks・ChatInterface の節に、動かしたコードと結果を載せています。

Q. Gradio は無料ですか？ 商用で使えますか？ A. ライブラリは Apache-2.0 で、無料で使えます。Hugging Face Spaces で公開する場合は、2026年10月17日時点で Gradio の Space の作成に有料プラン（PRO は月9ドル）が要り、無料の個人アカウントは ZeroGPU 上の Gradio の Space を2つまでです。

Q. Gradio の ChatInterface でチャットボットを作るには？ A. message と history を受け取って返事を返す関数を書き、gr.ChatInterface(fn=関数).launch() とします。yield で返すとストリーミングになります。Gradio 6 では history の content が辞書のリストになっています。

Q. Gradio と Streamlit の違いは？ A. Gradio は操作されたときに結んだ関数だけを動かし、API も自動でできます。Streamlit は操作のたびにスクリプト全体を上から動かし直します。違いの表と判断表を「GradioとStreamlitの違い」の節に載せています。

まとめ

• Gradio は、Python の関数に画面と API を付けるライブラリ。最新は 6.30.0 で、Python 3.10 以上が条件（3.9 では 4.44.1 が入る）。
• 作り方は、関数1つの gr.Interface、配置とイベントを書く gr.Blocks、チャットの gr.ChatInterface の3種類。
• API の名前は関数名（/greet）。gradio_client の predict、または curl の /gradio_api/call/名前 に POST → GET で呼べる。
• share=True のリンクは1週間で失効。auth でパスワードをかけられる。
• イベントは既定で1件ずつ処理される。同じ関数を結んだイベントはキューを共有する。
• Spaces の Gradio アプリの作成は、2026年10月17日時点で有料プランが条件（無料の個人は ZeroGPU で2つまで）。

参考・出典

確認日はいずれも 2026年10月17日です。

• Gradio「Quickstart」：https://www.gradio.app/guides/quickstart
• Gradio「Sharing Your App」：https://www.gradio.app/guides/sharing-your-app
• Gradio「Queuing」：https://www.gradio.app/guides/queuing
• Gradio「Environment Variables」：https://www.gradio.app/guides/environment-variables
• Gradio「How to Create a Chatbot with Gradio」：https://www.gradio.app/guides/creating-a-chatbot-fast
• Gradio「Getting Started with the Python Client」：https://www.gradio.app/guides/getting-started-with-the-python-client
• Gradio「Querying Gradio Apps with Curl」：https://www.gradio.app/guides/querying-gradio-apps-with-curl
• Gradio「API Page」：https://www.gradio.app/guides/view-api-page
• Gradio「Alerts」：https://www.gradio.app/guides/alerts
• GitHub「gradio-app/gradio」：https://github.com/gradio-app/gradio
• PyPI「gradio」：https://pypi.org/project/gradio/
• Hugging Face「Spaces Overview」：https://huggingface.co/docs/hub/spaces-overview
• Hugging Face「Gradio Spaces」：https://huggingface.co/docs/hub/spaces-sdks-gradio
• Hugging Face「Spaces Configuration Reference」：https://huggingface.co/docs/hub/spaces-config-reference
• Hugging Face「Pricing」：https://huggingface.co/pricing
• Streamlit「Basic concepts of Streamlit」：https://docs.streamlit.io/get-started/fundamentals/main-concepts
• Streamlit「Run your Streamlit app」：https://docs.streamlit.io/develop/concepts/architecture/run-your-app

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