Pyxelのインストールは、今あるPython・VS Codeに、ゲーム制作の道具を追加する作業です。この記事では、専用の作業フォルダーを作り、最初の丸が表示されるところまで進めます。
対象はWindows 11です。Python・VS Code・MicrosoftのPython拡張機能を用意し、print("Hello")を実行できる状態から始めます。まだの場合は、Python・VS Codeの環境構築ガイドを先に進めてください。Macなどはコマンドの書き方が異なります。
1. Pyxel用のフォルダーを作ろう
- ドキュメントなど、自分が保存できる場所に
pyxel-playgroundというフォルダーを作ります。 - VS Codeで「ファイル」→「フォルダーを開く」を選び、このフォルダーを開きます。
- 「ターミナル」→「新しいターミナル」を選びます。WindowsではPowerShellで進めます。
VS Codeの左側にpyxel-playgroundが表示され、下のターミナルの場所もこのフォルダーになっていることを確かめます。以後の命令は、下のターミナルへ1行ずつ入力してEnterを押します。

ターミナルのPS C:\…>などの表示は入力しません。>>>が出ている場合はPythonの対話モードです。exit()を入力してEnterで抜けてから進めます。
2. 仮想環境を作り、Pyxelを入れる
2-1. Pythonのバージョンを確認
python --version
公式ガイドの対応条件はPython 3.11以降です。Python 3.12.xなど、3.11以上の番号を確認します。3.10以前、または命令が見つからない場合は、Python本体の準備を確認してください。既存のPythonを削除する必要はありません。
2-2. この作品用のPython環境を作る
python -m venv .venv
仮想環境は、作品ごとに追加の道具を分けるための入れ物です。左のファイル一覧に.venvフォルダーができれば、作成できています。この中のファイルを手作業で編集する必要はありません。
2-3. その環境にPyxelをインストール
.\.venv\Scripts\python.exe -m pip install pyxel
ダウンロードとインストールが終わり、入力できる状態に戻るまで待ちます。Successfully installedやRequirement already satisfiedは、インストール完了・導入済みの目印です。続いて確認します。
.\.venv\Scripts\python.exe -m pip show pyxel
Name: pyxelとVersion:が表示されたら成功です。Locationの保存先が、今の作品の.venvの中になっていることも確かめましょう。
.\.venv\Scripts\python.exe は、「この作品のPythonを使う」という指定です。この方法ではActivate.ps1の実行や、PowerShellの実行ポリシーの変更は不要です。3. VS Codeでも同じPythonを選ぶ
- Ctrl+Shift+Pを押します。
Python: Select Interpreterを入力して選びます。日本語表示では「Python: インタープリターを選択」と表示される場合があります。.venvのPythonを選びます。見つからない場合は「Enter interpreter path…(インタープリターパスを入力)」→「Find…」から、作品フォルダー内の.venv → Scripts → python.exeを選びます。
右上の実行ボタンも、ここで選んだPythonを使います。インストール先と実行先をそろえると、「入れたはずなのに見つからない」という混乱を防げます。
4. 最初の画面を表示しよう
- 左のファイル一覧で、新しいファイル
hello_pyxel.pyを作ります。.venvの中ではなく、作品フォルダー直下です。 - 下のコードを貼り付け、Ctrl+Sで保存します。
- ターミナルで、コードの下の実行命令を入力します。
import pyxel
pyxel.init(160, 120, title="Hello Pyxel")
pyxel.cls(1)
pyxel.circ(80, 60, 12, 10)
pyxel.show()
.\.venv\Scripts\python.exe hello_pyxel.py
別ウィンドウに青い背景と黄色い丸が出たら成功です。160×120は画面内の点の数です。実際のウィンドウは見やすい大きさに拡大されます。

画面を閉じるには、Pyxelのウィンドウを選んでEsc、または右上の閉じるボタンを使います。起動したターミナルでCtrl+Cでも終了できます。終了前は、そのターミナルがPyxelを動かしているので、次の命令を入力するのは閉じてからにしましょう。
title="Hello Pyxel"の言葉だけを変えて保存し、もう一度実行してください。ウィンドウのタイトルはどう変わりましたか?
Pyxelがインストール・実行できないとき
「.venv…python.exeが見つからない」
ターミナルが作品フォルダーにいるか、.venvを作る手順が成功したか確認します。別のフォルダーを開いている場合は、VS Codeでpyxel-playgroundを開き直し、新しいターミナルを作ります。
ModuleNotFoundError: No module named ‘pyxel’
実行しているPythonが、インストールしたPythonと異なる可能性があります。まずこの記事の長い実行命令で試し、そのあとVS Codeのインタープリター選択を確認しましょう。
「pyxel」が認識されない
pyxelという短い命令の保存場所を見つけられていない状態です。この記事では専用Pythonのフルパスに近い指定を使うため、PATHをむやみに変更する必要はありません。エディターも同じ環境から起動できます。
Pyxelの命令がない/importで変なエラーが出る
自分のファイルにpyxel.pyという名前を付けていないか確認します。ライブラリと同じ名前にすると、読み込む対象がぶつかります。見本どおりhello_pyxel.pyにして、再実行してください。
PowerShellにスクリプト実行の警告が出た
VS Codeが仮想環境を自動的に有効化しようとしている場合があります。この教材の.\.venv\Scripts\python.exeを使う方法は、有効化しなくても実行できます。警告を消すためだけにセキュリティ設定を変更しないでください。
インストールの最後が赤いエラーになる
Pythonの番号、インターネット接続、管理PCの利用制限を確かめます。末尾の数行を読むと原因の手がかりになります。対応する配布ファイルが見つからない場合は、公式の対応条件を確認し、同じ命令を何度も繰り返す前に原因を調べましょう。
準備できたら、色と位置を変えて遊ぼう
確認した環境と公式資料
この記事のコードはPyxel 3.0.1・Python 3.12のLinux環境で動作を確認しています。Windows 11向けの操作・コマンドを案内していますが、Windows実機での一連の操作確認は未実施です。画面や対応バージョンは更新で変わるため、導入できないときは公式資料も確認してください。
パイソンチャレンジャーズによる独自教材です。Pyxelの公式サイトではありません。
