How to use the web version of Pyxel, a retro game engine for Python

(This article is a translation of an earlier Japanese posting 日本語版の記事はこちら)

It has already been four years since the first release in June 2018. Little by little, with added features and improvements, Pyxel, the retro game engine for Python, is now at version 1.8.

The theme of the Pyxel 1.8 series is the expansion of supported platforms.

Pyxel was originally multi-platform, but 1.8 expands support to the following platforms:

And the last major platform that is currently being developed at a rapid pace is the web browsers.

The web version of Pyxel is just now getting a full set of functions working, and I am already seeing a variety of potential applications, so I would like to introduce some interesting aspects of the web version of Pyxel and its basic usage.

About Pyxel, a retro game engine

I think (hope) that the number of people who use Python and have never heard of Pyxel is becoming fewer and fewer, but Pyxel is a game engine that makes it easy to create pixel-art type games in Python.

For more details, please refer to the official website ( A brief review of its features is as follows:

  • Simple specifications and an easy API make it easy to enjoy game creation
  • Graphics and sound production tools are included
  • It's a Python module, so it can be used in combination with other packages

Thanks to users' support, the number of stars on GitHub has exceeded 10,000, making it the most popular game library for Python in terms of the number of stars, and the most popular open source game engine in the world as a whole, ranking 5th or 6th. I feel that it was a good thing that a game engine from Japan was able to show its presence to the world.

By the way, in France, there is a large scale programming contest using Pyxel as a theme, in which over 400 schools participate. (If anyone has any ideas for a project, please let me know!)

How to install the web version of Pyxel

The web version of Pyxel, which began to be supported in 1.8, has become dramatically lower to use through the use of Web technology.

Until now, it was possible to install Pyxel as a Python package with a single command using pip install -U pyxel, but it required prior preparation such as installing Python and making the pip command usable.

On the other hand, with the web version of Pyxel, all you need to do is add the following line to your HTML file and you are ready to go.

<script src=""></script>

No Python installation or pip setup required!

Also, if you have the Pyxel code and application (.pyxapp) on GitHub, you can run it by simply specifying the file location in Pyxel Web Launcher URL, without even creating an HTML file.

Execute Python commands directly

Now let's actually write a Pyxel program in Python.

If you want to run Python code directly, write the code you want to run in HTML in the script attribute of the pyxel-run tag. For example, you can create a file like this:

<script src=""></script>
<pyxel-run script="
import pyxel
pyxel.init(200, 150)
pyxel.line(20, 20, 180, 130, 7)

Save it with an appropriate file name, such as pyxel.html, and open it in a web browser to display the following screen.

You can see that the Python + Pyxel code can be executed without any preparation.

The file format is normal HTML, so it can be combined with other web services.

For example, you can use the online web prototyping environment Code Pen to enter code to run Pyxel in the same way.

See the Pen pyxel-run test by Takashi Kitao (@kitao) on CodePen.

It is interesting that Python is running on a site for the web development (HTML/CSS/JavaScript).

Run Python files

If you want to load and run a separate file instead of writing Python code in an HTML file, use the root and name attributes of the pyxel-run tag.

The root is the directory from which you want to search for the file, and the name is the name of the file. The file name is relative to the starting point.

For example, if the Python code mentioned earlier is named and placed in the same directory as the HTML file, it would be written like this:

<script src=""></script>
<pyxel-run root="." name=""></pyxel-run>

Note that the root attribute can be omitted if the starting point is the current directory ('.'), the root attribute can be omitted.

The way to execute a file is to set up a server for execution, since it is prohibited to load another local file directly from a local HTML file.

If you can use Python, you can start a server from the current directory by typing the following in the directory where you placed the file.

python -m http.server
# For Mac or Linux, use python3 instead of python

It can then be accessed from a browser as http://localhost:8000/pyxel.html.

You can also specify a URL in the starting directory as follows:

See the Pen pyxel-triangle by Takashi Kitao (@kitao) on CodePen.

In this case, the file to be read is not local, so it can be viewed directly in the browser without setting up a server.

Run a Pyxel application

Similarly, Pyxel applications (.pyxapp) can be played using the pyxel-play tag.

See the Pen pyxel-megaball by Takashi Kitao (@kitao) on CodePen.

Use other packages

Any package supported by Pyodide can be used with the web version of Pyxel.

To install a package, specify the package name in the pyxel-run or pyxel-play element, separated by commas, as in packages="package1,package2,...".

Use The Virtual Gamepad

You can use a virtual gamepad on a touch device by adding gamepad="enabled" to the pyxel-run and pyxel-play tags as follows:

 <pyxel-run name="" gamepad="enabled"></pyxel-run>

The virtual gamepad converts touch input to the screen into the following gamepad buttons' input.


Run a Pyxel application with Pyxel Web Launcher.

If you have a Python code file or a Pyxel app (.pyxapp) on GitHub, you can launch it directly with the Pyxel Web Launcher.

The format for launching a Pyxel app with Pyxel Web Launcher is as follows:<github_user_name>.<repository_name>.<app_directory>.<pyxapp_name_without_extension>

For example, if your username is taro, your repository name is taro_repo, your app directory is dist/games, and your app name is shooter.pyxapp,

will be the URL.


Here is a link to a list of examples of the web version of Pyxel. Please refer to it as a reference, as it uses all the features for the web at hand.

Since the web version of Pyxel is easy to install and can be combined in various ways, you can realize various things depending on your ideas, such as an online development environment for Pyxel.

I hope that you will try your hand at various challenges as well. I am looking forward to hearing from you!