[Linux] [uv] wxPythonで作ったツールをuvxで動かしたい

2025.11.05

近頃はwxPythonを使ってMac・Windows・Linuxで動作する簡易GUIツールを色々作っています。また、uvを導入したことで、ツールのプロジェクト管理や実行環境の管理も手軽になりました。

しかし、uvの便利なコマンドuvxを使って拙作ツールVenv CleanerをXubuntu 24.04上で実行するとwxPythonのビルドが始まってしまい、以下のビルドエラーが発生して実行できませんでした。

~$ uvx venvcleaner
  × Failed to build `wxpython==4.2.4`
  ├─▶ The build backend returned an error
  ╰─▶ Call to `setuptools.build_meta.build_wheel` failed (exit status: 1)

エラーの詳細は以下に記したとおりですが、まさかpyenvが原因とは思わなかったので、解決するまで時間がかかりました。

uvxで発生したエラーの詳細はこの中にあります。読み飛ばして構いません。

--verboseオプションを使ってエラーの詳細を調べたところ、以前からインストールしてあったpyenvが以下のようなエラーを起こしていました。

err: pyenv: python3.13-config: command not found

The `python3.13-config' command exists in these Python versions:
  3.13.3

Note: See 'pyenv help global' for tips on allowing both
      python2 and python3 to be found.

pyenv globalとuv python find --systemでとpyenv側とuv側のPythonバージョンを調べると、それぞれ3.12と3.13でした。uvxの実行中にwxPythonのビルドはPython 3.13を使っていましたので、PATHが優先されていたpyenv側のpython3.13-configが呼び出されて、上記のエラーを引き起こしていました。

pyenv global 3.13を実行してpyenv側もPythonのバージョンを3.13に変えると、wxPythonのビルド自体は(いくつかライブラリが見つからないという警告は残りましたが)一応成功しました。

でも、ビルドの完了には数分間かかる上、ツール実行時に必要なライブラリバージョンが見つからないというエラーが発生します。

    import wx
  File "/home/中略/lib/python3.13/site-packages/wx/__init__.py", line 17, in <module>
    from wx.core import *
  File "/home/中略/lib/python3.13/site-packages/wx/core.py", line 12, in <module>
    from ._core import *
ImportError: /lib/x86_64-linux-gnu/libwx_baseu-3.2.so.0: version `WXU_3.2.6' not found (required by /home/中略/lib/python3.13/site-packages/wx/_core.cpython-313-x86_64-linux-gnu.so)

pyenvが入っていない環境ではこのようなエラーは発生しなかったので、結局、PATH環境変数からpyenvへのパスを削除してみたところ、ツールが正常に動作するようになりました。

# PATH環境変数からpyenvへのパスを削除した状態で、以下のコマンドを実行 (Xubuntu 24.04)
uv cache clean
uv venvcleaner

ちなみに、MacやWindowsではuvxで簡単に動きます。uvx venvcleanerと入力するだけで、ツールと一緒にビルド済みのwxPythonがダウンロードされます。

本記事は、LinuxでもwxPythonで作ったツールをuvxで手軽に動かす手順を確立したいと思って書き始めましたが、色々あってなかなか難しいと思いました😅。

Linuxでもビルド済みwxPythonをuvxでインストールしたい

Linuxでは、ソースコードで配布されているパッケージをインストールするためにはビルド環境を整える必要がある(こちらとこちらの記事を参照)ので、もしビルド済みのバイナリパッケージ(wheelファイル)があるなら、それをインストールするのが楽です。

x86-64用Linux向けには、wxPythonのビルド済みバイナリパッケージ(wheelファイル)がwxPython Downloadsに公開されています。説明を引用(日本語訳)すると:

はい、Linux Wheels はあります。まあ一応ね。

Linuxディストリビューション間の違い（主にデフォルトでインストールされるコアライブラリのバージョンの違い、プラットフォームアーキテクチャなど）により、PEP 513の制約内で動作させない限り、Linux用のバイナリwheelファイルをPyPIでホストすることはできません。残念ながら、wxPythonをmanylinux1の枠に無理やり当てはめようとする試みは、あまり成功していません。manylinux2の方が適合する可能性があります。当面は、 wxPython Extras Linuxフォルダにあるwheelのビルドに使用されたLinuxと十分に類似したLinuxをお持ちであれば 、それらを使用すれば、wheelを自分でビルドする必要はありません。

ちなみに、manylinuxはUbuntu・Fedora・CentOS・Debianなど多くのLinuxディストリビューションでバイナリ配布(wheelファイル)を互換的に動かすための標準仕様(PEP 513やPEP 600など)です。

自分の環境に合ったwxPythonをwxPython Extras Linuxフォルダから取得する方法については、wxPython Downloadsではpipを使って取得するコマンドが例示されています:

pip install -U -f https://extras.wxpython.org/wxPython4/extras/linux/gtk3/ubuntu-16.04 wxPython

uvxにも-f (--find-links)オプションがあるので、これを使って自分の環境に合ったwxPythonを指定することができます。上の例に倣えばこんな感じになります(Ubuntu 24.04の場合):

uvx -f https://extras.wxpython.org/wxPython4/extras/linux/gtk3/ubuntu-24.04 venvcleaner

uvx にも-Uオプションはあるのですが、uv 0.9.7では以下の警告メッセージが表示されるため、-Uは外しました。アップグレードはuv tool upgrade --allやuvx パッケージ名@latestを使います。

warning: Tools cannot be upgraded via `uvx`; use `uv tool upgrade --all` to upgrade all installed tools, or `uvx package@latest` to run the latest version of a tool.

これでpyenvが同居している環境であっても、wxPythonを用いたツールをuvxで実行できるようになりました。でも、毎回長いダウンロードURLを入力してuvxを実行するのは面倒です😅。

URLの入力が大変なのでuv tool installでインストール

エイリアスやシェルスクリプトを作ってuvxを動かしても良いと思いますが、それならばuv tool installでuvの永続環境にツールをインストールしても良いかと思います。

uv tool installも-f (--find-links)オプションでダウンロードURLを指定できます:

uv tool install -f https://extras.wxpython.org/wxPython4/extras/linux/gtk3/ubuntu-24.04 venvcleaner

uv 0.9.7では、uv tool installでインストールしたツールは$HOME/.local/binにシンボリックリンクが作られます。PATH環境変数に$HOME/.local/binが入っていれば、ツールの名前を入力するだけで動きます。

venvcleaner

uvでインストールしたツールはuv tool uninstallで容易にアンインストールできます:

# インストールされているツールの一覧を取得
uv tool list

# ツールをアンインストール
uv tool uninstall venvcleaner

# すべてのツールをアンインストール
uv tool uninstall --all

これで、Linuxでもuvを使って手軽にwxPythonを使ったツールを動かせるようになったとひとまず安心したのも束の間、ダウンロードURLを変えて試してみると別の問題があることに気付きました。結構思ったより大変です、、、😨

ビルド済みwxPythonのバージョンは古い場合がある

環境に合ったURLをコピーして-fオプションに指定できるように、LinuxディストリビューションごとのwxPythonのダウンロードURLを下記にまとめていたのですが、ここで問題があることに気付きました。

それは、古いバージョンのディストリビューションではwxPythonのバイナリwheelファイルの更新が止まっているため、-fオプションを指定しても新しいバージョンのソースコードをダウンロードしてビルドしてしまうことです。

例えば、Ubuntu 20.04用のダウンロードURLを指定した場合:

~$ uv tool uninstall --all;uv cache clean
Removed dangling environment for `venvcleaner`
Clearing cache at: .cache/uv
Removed 15895 files (324.5MiB)
~$ uv tool install -f https://extras.wxpython.org/wxPython4/extras/linux/gtk3/ubuntu-20.04 venvcleaner
Resolved 3 packages in 200ms
   Building wxpython==4.2.4

Ubuntu 20.04用wheelファイルはバージョン4.2.3で更新が止まっており、本ページを書いている時点で最新のバージョン4.2.4は公開されていません。uvは(そしてpipもですが)、PyPIから新しいバージョンのwxPythonのソースコードをダウンロードしてビルドします。つまり、状況は本ページの最初に戻ってしまいます😢。

最新版のwxPythonをインストールしてしまう理由は、ツール側のpyproject.tomlの依存関係でwxPython >= 4.2.3としているため、この条件に該当する最新のwxPythonがインストールされてしまいます。

dependencies = [
    "click>=8.3.0",
    "wxpython>=4.2.3",
]

強制的にビルド済みの古いwxPythonをインストールするには、uv tool installに--with パッケージ名==バージョンを指定します。

# ダウンロードURLとwxPythonのパッケージのバージョンを指定する
uv tool install \
    -f https://extras.wxpython.org/wxPython4/extras/linux/gtk3/ubuntu-20.04 \
    --with wxPython==4.2.3 \
    venvcleaner

LinuxディストリビューションごとのwxPythonのダウンロードURLは以下にまとめてあります。これらのURLはWebブラウザで開くことができます。どのバージョンのwxPythonがバイナリwheelファイルとして公開されているのかを確認できますので、wheelファイルの命名規則を参考にPythonのバージョンとwxPythonのバージョンを調べて、--withオプションにバージョンを指定してください。

Ubuntu用のダウンロードURL一覧はこちら。

Ubuntu 24.04:

https://extras.wxpython.org/wxPython4/extras/linux/gtk3/ubuntu-24.04

Ubuntu 22.04:

https://extras.wxpython.org/wxPython4/extras/linux/gtk3/ubuntu-22.04

Ubuntu 20.04:

https://extras.wxpython.org/wxPython4/extras/linux/gtk3/ubuntu-20.04

Ubuntu 18.04:

https://extras.wxpython.org/wxPython4/extras/linux/gtk3/ubuntu-18.04

Ubuntu 18.04 GTK2用:

https://extras.wxpython.org/wxPython4/extras/linux/gtk2/ubuntu-18.04

Ubuntu 16.04:

https://extras.wxpython.org/wxPython4/extras/linux/gtk3/ubuntu-16.04

Ubuntu 16.04 GTK2用:

https://extras.wxpython.org/wxPython4/extras/linux/gtk2/ubuntu-16.04

Ubuntu 14:04:

https://extras.wxpython.org/wxPython4/extras/linux/gtk3/ubuntu-14.04

Ubuntu 14:04 GTK2用:

https://extras.wxpython.org/wxPython4/extras/linux/gtk2/ubuntu-14.04
Rocky Linux用のダウンロードURL一覧はこちら。

Rocky Linux 9:

https://extras.wxpython.org/wxPython4/extras/linux/gtk3/rocky-9

Rockey Linux 8:

https://extras.wxpython.org/wxPython4/extras/linux/gtk3/rocky-8
Fedora用のダウンロードURL一覧はこちら。

Fedora 38:

https://extras.wxpython.org/wxPython4/extras/linux/gtk3/fedora-38

Fedora 37:

https://extras.wxpython.org/wxPython4/extras/linux/gtk3/fedora-37

Fedora 36:

https://extras.wxpython.org/wxPython4/extras/linux/gtk3/fedora-36

Fedora 35:

https://extras.wxpython.org/wxPython4/extras/linux/gtk3/fedora-35

Fedora 31:

https://extras.wxpython.org/wxPython4/extras/linux/gtk3/fedora-31

Fedora 30:

https://extras.wxpython.org/wxPython4/extras/linux/gtk3/fedora-30

Fedora 29:

https://extras.wxpython.org/wxPython4/extras/linux/gtk3/fedora-29

Fedora 28:

https://extras.wxpython.org/wxPython4/extras/linux/gtk3/fedora-28

Fedora 27:

https://extras.wxpython.org/wxPython4/extras/linux/gtk3/fedora-27

Fedora 26:

https://extras.wxpython.org/wxPython4/extras/linux/gtk3/fedora-26

Fedora 26 GTK2用:

https://extras.wxpython.org/wxPython4/extras/linux/gtk2/fedora-26

Fedora 24:

https://extras.wxpython.org/wxPython4/extras/linux/gtk3/fedora-24

Fedora 24 GTK2用:

https://extras.wxpython.org/wxPython4/extras/linux/gtk2/fedora-24

Fedora 23:

https://extras.wxpython.org/wxPython4/extras/linux/gtk3/fedora-23

Fedora 23 GTK2用:

https://extras.wxpython.org/wxPython4/extras/linux/gtk2/fedora-23
Debian用のダウンロードURL一覧はこちら。

Debian 11:

https://extras.wxpython.org/wxPython4/extras/linux/gtk3/debian-11

Debian 10:

https://extras.wxpython.org/wxPython4/extras/linux/gtk3/debian-10

Debian 9:

https://extras.wxpython.org/wxPython4/extras/linux/gtk3/debian-9

Debian 9 GTK2用:

https://extras.wxpython.org/wxPython4/extras/linux/gtk2/debian-9

Debian 8:

https://extras.wxpython.org/wxPython4/extras/linux/gtk3/debian-8

Debian 8 GTK2用:

https://extras.wxpython.org/wxPython4/extras/linux/gtk2/debian-8
CentOS用のダウンロード一覧はこちら。

CentOS 8:

https://extras.wxpython.org/wxPython4/extras/linux/gtk3/centos-8

CentOS 7:

https://extras.wxpython.org/wxPython4/extras/linux/gtk3/centos-7

CentOS 7 GTK2用:

https://extras.wxpython.org/wxPython4/extras/linux/gtk2/centos-7

少し前のディストリビューションでは、Pythonのバージョンが3.11 止まりでwxPythonもバージョン4.2.1止まりでしたので、Venv Cleanerでサポートするバージョンを見直す予定です。

蛇足：wxPythonのビルド環境が整っていればuvxで動きます

ただし、初回の起動にはとても時間がかかりますが、、、

Raspberry PiなどのARM版Linuxのようにビルド済みのwxPythonが無い場合は仕方ありませんので、ツールを実行する前に予めビルド環境を整えます。

以下の記事を参考に、例としてRaspberry Pi 400にクリーンインストールしたRaspberry Pi OS バージョン 13 (trixie)を使ってビルド環境を整えてみました。

  1. Building wxPython for Linux via Pip
  2. wxWidgets for GTK installation
# uvのインストール
curl -LsSf https://astral.sh/uv/install.sh | sh
source "$HOME/.local/bin/env"

# 1. python-dev(Pythonのビルドに必要なパッケージ)のインストール
#  -> https://devguide.python.org/getting-started/setup-building/index.html
sudo apt-get update
sudo apt-get install build-essential gdb lcov pkg-config \
      libbz2-dev libffi-dev libgdbm-dev libgdbm-compat-dev liblzma-dev \
      libncurses-dev libreadline-dev libsqlite3-dev libssl-dev \
      lzma liblzma-dev tk-dev uuid-dev zlib1g-dev libmpdec-dev libzstd-dev \
      inetutils-inetd

# 2. Prerequisites (wxWidgetsのビルドに必要なパッケージのインストール)
sudo apt-get install libgtk-4-dev libglu1-mesa-dev \
      libgstreamer-plugins-base1.0-dev libcurl4-openssl-dev \
      libwebkit2gtk-4.1-dev

この状態でuvxを使ってツールを実行します。

uvx venvcleaner

待つこと2時間半、wxPythonで作ったツールのウィンドウが表示されました。pyenvは入っていないので、ビルドエラーは起こっていません。

ビルドしたwxPythonはuvのキャッシュに残るので、次回以降ツールはすぐに起動します。

wxPythonのビルド環境を整えるにはディストリビューションやライブラリなど様々な条件があり得ますので、簡単かつ確実な手順にするのは難しそうです。Raspberry Pi OSの場合、wxWidgets for GTK installationに書かれているパッケージ名は少し異なっていたので、apt searchコマンドで似た名前のパッケージを探しました、、、

タイトルとURLをコピーしました