Install PyRat¶

This section provides instructions on how to install the PyRat library and set up your workspace. This is essential to start developing games using the PyRat API.

Note

You can also find these installation instructions in the README file on the GitHub repository.

In short¶

If you are in a hurry, and already have uv installed, this is the whole installation:

uvx --python 3.13 --from pyrat-game pyrat-init
cd pyrat_workspace
uv run games/sample_game.py

The rest of this page explains each of these steps.

Prerequisites¶

This installation procedure assumes that you have basic knowledge about shell manipulation.
PyRat uses uv to manage Python and the libraries it needs. You do not need to install Python yourself: uv takes care of it, and downloads the version PyRat needs if your machine does not have it.
Finally, we will test PyRat installation using Visual Studio Code (VSCode), as this is the main tool we use in the associated course. Please make sure it is already installed, or install it from the official website. Note that you can use a different tool if you want, but we just provide indications for that one here.

Step 1 – Install uv¶

If uv is not installed on your machine yet, install it as follows.

Linux

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

MacOS

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

Windows (PowerShell)

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Other installation methods are described in the uv documentation.

Important

Close and reopen your terminal after installing uv, otherwise the uv command will not be found. You can then check that everything went well by running uv --version.

Step 2 – Setup your PyRat workspace¶

We are now going to create a workspace for PyRat. This is a directory that contains minimal working examples to get started, and in which PyRat is installed.

Open a terminal, and navigate (use the cd command) to the directory where you want to create your PyRat workspace.
Run the following command, which is the same on all systems:
```
uvx --python 3.13 --from pyrat-game pyrat-init
```

Note

PyRat cannot be used with Python 3.14 and later, as pygame (one of the libraries PyRat needs) cannot be installed with these versions. This is why the command above asks uv to use Python 3.13.

You should see something like this:

Workspace created in /path/to/pyrat_workspace, as a uv project using Python >=3.12,<3.14
Git repository created for the workspace
Using CPython 3.13.13
Creating virtual environment at: .venv
Resolved 20 packages in 178ms
Installed 19 packages in 45ms
Virtual environment created, with PyRat installed in it
Your workspace is ready! You can now start coding your players and run games.
To run a game, go to the workspace using 'cd pyrat_workspace', then use for instance 'uv run games/sample_game.py'.

You should have a new directory called pyrat_workspace in the directory where you ran the command.

Tip

If you prefer another name, pass it to the command, as in uvx --python 3.13 --from pyrat-game pyrat-init my_project.

Here is what this directory contains:

pyrat_workspace
|_ games                   # The scripts that start a game
|_ players                 # The programs that control a character
|_ .venv                   # The virtual environment of the workspace, created by uv
|_ pyproject.toml          # The description of your project and of the libraries it needs
|_ uv.lock                 # The exact versions of the installed libraries
|_ README.md               # A description of the workspace
|_ .gitignore              # The files that Git should ignore

Important

PyRat installs a small file in the virtual environment of your workspace, which adds your workspace to the directories Python imports from. This is what allows a script in games to import a player from players, as in from players.random1 import Random1. Any directory you add to your workspace is importable the same way, with nothing to declare.

This file finds your workspace from the virtual environment it contains, rather than writing its path down, so you can rename or move your workspace with no command to run afterwards. It puts nothing in your workspace, which holds nothing but your programs and the files uv needs.

Step 3 – Check your installation¶

Now, we are going to verify that PyRat works properly.

From a terminal

Open a terminal, and navigate to your workspace using cd pyrat_workspace.
Run the sample game:
```
uv run games/sample_game.py
```

From VSCode

Open VSCode, and add your pyrat_workspace directory in your VSCode workspace.
Open the file sample_game.py in directory games/.
Make sure VSCode is using the interpreter located in the .venv directory of your workspace.
Run sample_game.py.

In both cases, you should see something like this:

What now?

Have a look at the Quick Overview to understand what you are seeing, then follow The Random Programs to write your first player.

Add other libraries to your workspace¶

Your workspace is a uv project, so you can add any library you need to it. To do so, run uv add from your workspace:

uv add numpy

The library is then available in your players and games, with no need to activate anything.

Rebuild your workspace¶

Your workspace describes everything it needs in its pyproject.toml and uv.lock files, so it can always be rebuilt. Run this from the workspace, for instance after cloning it on another machine, or if one of its libraries goes missing:

uv sync

This installs again everything your workspace declares, in a virtual environment created for your machine.

Note

Renaming or moving your workspace needs nothing. Your workspace is found from the virtual environment it contains, so your programs keep importing each other wherever the workspace is.

Install PyRat¶

In short¶

Prerequisites¶

Step 1 – Install uv¶

Step 2 – Setup your PyRat workspace¶

Step 3 – Check your installation¶

Add other libraries to your workspace¶

Rebuild your workspace¶

Troubleshooting¶