macOSでGUI付きPythonアプリケーションを動かす

macOSでGUIを使用したPythonアプリケーションを動かすための環境構築手順について、初心者向けの資料がなかったので作成しました。この記事では2025年10月時点で、できるだけ確実で手数が少なくかつ将来性のある手順を紹介するために、uvを導入します。
uvは、Pythonのバージョンやライブラリの管理を簡単にするツールです。Pythonは多様な外部ライブラリを活用できることが大きな強みです。一方で、古いPythonバージョンでしか正常に動作しないライブラリがあったり、ライブラリ同士が衝突して期待どおりに動かない場合もあります。uvは、こうしたトラブルを未然に防ぐのに役立ちます。
このページでは、macOSにuvをインストールし、GUI付きPythonアプリケーションの動作確認を行う手順を説明します。

前提

macOS のバージョンが極端に古い場合は、画面左上の → システム設定 → 一般 → ソフトウェアアップデートで macOS を最新にしておきましょう。
ここではHomebrewやXcode Command Line Tools(CLT)は使用しませんが、すでにインストールされていても問題ありません（何のことかよくわからない場合は、気にしなくて大丈夫です）。

Pythonをインストールする

公式サイトからPython 3.11のインストーラーをダウンロードしてインストールします。
どのバージョンをインストールするかは、これから使う外部ライブラリの対応状況で決めます。ライブラリによっては3.8などというかなり古いPythonにしか対応していないこともあります。現時点でどのバージョンがいいか決まっていない場合はひとまずStable Releasesの3.11 (macOS 64-bit universal2 installer)をインストールしておいて、あとから追加変更すればいいです。Pythonの各バージョンの公開状況はこちらで確認できます。
また、通常uvを使用する場合はわざわざPythonを公式サイトからインストールする必要はない(後述)のですが、公式からインストールしておいた方がトラブルが少ないので、ここではあえて公式サイトからインストールする手順を説明しています。特にGUI付きのアプリケーションを動かす場合は、公式サイトからインストールしたPythonを使用することをお勧めします。
当研究室で公開しているBehavior SenpaiやTimeline-kunはPython 3.11で動作確認を行っています。

ターミナルを使用する

画面右上の🔍（Spotlight）をクリックし、terminal と入力 → ターミナル起動してください。

uvを導入する

もしかすると、過去にuvをインストールしているかもしれないので確認しましょう。ターミナルで以下のコマンドを実行します。

uv --version

もし以下のような感じにバージョンが表示されたら、uvはすでにインストールされています。

>> uv 0.9.5 (d5f39331a 2025-10-21)

uvのバージョンが古すぎると期待どおりの動作をしない可能性があるため、以下のコマンドでuvを最新に更新します。

uv self update

もし以下のようなメッセージが表示されたら、uvはまだインストールされていません。

>> zsh: command not found: uv

その場合は、以下のコマンドでuvをインストールします。

curl -LsSf https://astral.sh/uv/install.sh | sh

最新のインストールに関する情報はこちらを参照。インストールが終わったら、ターミナルをいったん閉じて再度開きます。

作業をする場所を作る

ホーム/書類フォルダの中に「projects」フォルダを作成することをお勧めします(フォルダの名前はなんでもいいですが、全角文字の使用は避けましょう)。
フォルダを作ったら、ターミナルでそのフォルダに移動します。Finderでは勝手に翻訳されて「書類」というフォルダ名になっていますが、実際の名前は「Documents」なので注意。

cd ~/Documents/projects

動作確認用Pythonプロジェクトを作成する

今いる場所がprojectsフォルダであることを確認してください。

pwd

結果が以下のようになっていればOKです。

>> /Users/ユーザー名/Documents/projects

もし違う場合は、cdコマンドでprojectsフォルダに移動してください。
以下のコマンドで"mysample"という名前のプロジェクト(作業フォルダ)を作成します。

uv init mysample

mysampleフォルダに移動します。

cd mysample

mysampleで使用するPythonを設定します。ここでは、さきほどインストールしたPython 3.11を指定します。

uv python pin /Library/Frameworks/Python.framework/Versions/3.11/bin/python3.11

(参考)以下のコマンドでPythonバージョンを指定すると、わざわざ公式からPythonをインストールしなくてもuvが管理しているPythonを使用することができます。ただし、GUI付きのアプリケーションを動かす場合は公式サイトからインストールしたPythonを使用することをお勧めします。

(参考) uv python pin 3.11

Pythonを起動し、Pythonのバージョンをチェックします。

uv run python --version

以下のような感じにPythonのバージョンが表示されれば成功です。

>> Python 3.11.X

外部ライブラリを追加する

先程のtkinterはPythonに最初から含まれているライブラリでしたが、外部ライブラリを使用するときは追加してあげる必要があります。
例えば、画像処理ライブラリのPillowをインストールするには以下のコマンドを実行します。

uv add pillow

インストールが完了したら、以下のコマンドでPillowが正しくインストールされたか確認します。

uv tree

以下のような感じで、Pillowが表示されていれば成功です。Pillowのバージョンは、そのときに使用可能な最新版が入ります。

>> mysample v0.1.0
    └── pillow v12.X.X

Pillowは大丈夫ですが、ライブラリによってはuv addでうまくインストールできない場合があります。そのときは以下のようにすることもあります。

(参考) uv pip install ライブラリ名

GUI付きのPythonアプリを動かす

mysampleフォルダの中に、main.pyというファイルがあるはずです。main.pyをテキストエディットで開くと何かコードが書かれていると思いますが、それは全て消して、以下のコードに書き換えます。

import tkinter as tk
from PIL import Image, ImageTk, ImageDraw

img = Image.new("RGB", (240, 240), "white")
draw = ImageDraw.Draw(img)
draw.ellipse((40, 40, 200, 200), fill="skyblue")
draw.text((78, 110), "Hello", fill="black")

root = tk.Tk()
root.title("tkinter + Pillow")

tk_img = ImageTk.PhotoImage(img)
label = tk.Label(root, image=tk_img)
label.pack(padx=12, pady=12)

def rotate():
    global img, tk_img
    img = img.rotate(90, expand=True)
    tk_img = ImageTk.PhotoImage(img)
    label.config(image=tk_img)

btn = tk.Button(root, text="Rotate", command=rotate)
btn.pack(pady=(0, 12))

root.mainloop()

このコードは、"Rotate"ボタンを押すと"Hello"と書かれた円が90度回転する簡単なGUIアプリケーションです。書き換えたらファイルを保存して閉じます。
ターミナルで以下のコマンドを実行して、アプリケーションを実行します。mysampleフォルダにいることを確認してください。

uv run python main.py

2025年10月現在、uv python pin 3.11でPythonをインストールしている場合、macOS環境では以下のようなエラーが出ることがあります。

>> _tkinter.TclError: invalid command name "PyImagingPhoto"
   ...
   TypeError: bad argument type for built-in operation

今回は公式サイトからPythonをインストールしているため上記のエラーは出ないはずです。

まとめ

このページでは、macOS環境でGUI付きのPythonアプリケーションを動かすために環境構築を行う以下の手順を説明しました。

公式サイトからPythonをインストールする
uv initでプロジェクトを作成する
uv pinで使用するPythonを指定する
uv addで必要な外部ライブラリを追加する
uv run pythonでPythonアプリケーションを実行する

macOSにuvをインストール

西村英伍研究室