-
-

Python Bindings for Raylib 5.5

-
-

Libraries: raymath, raygui, rlgl, physac and GLFW

-
-
-

Backends: Desktop, SDL, DRM, Web

-
-
-

Platforms: Windows, Mac, Linux, Raspberry Pi, Web

-

PyPI - Downloads

-

Chatroom: Discord

-

HELP WANTED: writing examples

-

Features:

+
+

Python Bindings for Raylib 4.2

+

New CFFI API static bindings.

    -

  • CFFI API static bindings.

  • Automatically generated to be as close as possible to original Raylib.

  • Faster, fewer bugs and easier to maintain than ctypes.

  • Commercial-friendly license.

  • Docstrings and auto-completion.

    • -

  • Type checking with Mypy

    • +

  • Now includes extra libraries: raymath, raygui, rlgl and physac

Full documentation

-
-

Quickstart

-

pip3 install raylib==5.5.0.2 --break-system-packages

-
from pyray import *
-init_window(800, 450, "Hello")
-while not window_should_close():
-    begin_drawing()
-    clear_background(WHITE)
-    draw_text("Hello world", 190, 200, 20, VIOLET)
-    end_drawing()
-close_window()
+
Quickstart

+
pip3 install raylib

+
from pyray import *
+init_window(800, 450, "Hello")
+while not window_should_close():
+    begin_drawing()
+    clear_background(WHITE)
+    draw_text("Hello world", 190, 200, 20, VIOLET)
+    end_drawing()
+close_window()
-

Installation

-

If you are on a modern Linux you will probably want to create a venv:

-
python3 -m venv venv
-source venv/bin/activate
-
-
-

Then make sure you have the latest pip installed:

+

Installation

+

First make sure you have the latest pip installed:

python3 -m pip install --upgrade pip

Then install

-
python3 -m pip install setuptools
-python3 -m pip install raylib==5.5.0.2
+
python3 -m pip install raylib
 

 

-
On most platforms it should install a binary wheel.  If yours isn’t available then pip will attempt to build from
-source, in which case you will need to have Raylib development libs installed, e.g.
+
On most platforms it should install a binary wheel (Windows 10 x64, MacOS 10.15 x64, Linux Ubuntu1804 x64).

+
If yours isn’t available then pip will attempt to build from source, in which case you will need to have Raylib development libs installed, e.g.
 using homebrew, apt, etc.

-

-
Windows

-
Binaries require x64 Windows 10 or newer.  (For x86 or older Windows you will have to build from source.)

-
Use an official Windows Python release rather than WSL, MSYS, etc.

-

-

-
MacOS

-
Binaries require:

-
    
-
  • arm64 MacOS 14
    • 
-
  • x64 MacOS 10.13, or newer.
    • 
-

-
Older MacOS requires building from source but this is usually simple:

-
brew install pkg-config
-brew install raylib
-python3 -m pip install raylib==5.5.0.2
-

-

-
(I do have binaries for arm64 MacOS 11, 12 and 13 but I have no way of testing they work, so post an issue
-if you want to test them.)

-

-

-
Linux

-
Binaries require OS newer than Ubuntu 2020, x64 or arm64.   Otherwise build from source.
-(Pip should attempt automatically but will need Raylib itself installed and also pkg-config.)

-
The arm64 binaries are built on Raspberry Pi arm64 Bullseye with OpenGL 2.0
-so may not work on other boards.

-

 

-
Raspberry Pi

-
Using on Rasperry Pi

+
Raspberry Pi

+
Using on Rasperry Pi

 

-
-
-

Backends

-

Dynamic binding version

+

Dynamic binding version

There is now a separate dynamic version of this binding:

-
python3 -m pip uninstall raylib
-python3 -m pip install raylib_dynamic
+
python3 -m pip install raylib_dynamic
 

 

 
It works on some systems where the static version doesn’t, but be sure to read these caveats before using it

-
You can’t have multiple raylib packages installed at once.
-
-

SDL backend

-

This is not well tested but has better support for controllers:

-
python3 -m pip uninstall raylib
-python3 -m pip install raylib_sdl
+

+
Beta testing

+
If you find a bug, it may be fixed in the latest dev release.
+You can install an alpha or beta version by specifying the exact version number like this:

+
python3 -m pip install raylib==4.2.0.0.dev4
 

 

-
You can’t have multiple raylib packages installed at once.

-

-

-
DRM backend

-
This uses the Linux framebuffer for devices that don’t run X11/Wayland:

-
python3 -m pip uninstall raylib
-python3 -m pip install raylib_drm
-

-

-
You can’t have multiple raylib packages installed at once.

 

 

-
Problems?

-
If it doesn’t work, try to build manually..  If that works then submit an issue
+
Problems?

+
If it doesn’t work, try to build manually..  If that works then submit an issue
 to let us know what you did.

-
If you need help you can try asking on our discord.  There is also a large Raylib discord
-for issues that are not Python-specific.

+
If you need help you can try asking on Discord.

 
If it still doesn’t work, submit an issue.
-

How to use

-

There are two modules in the raylib package, raylib and pyray. (There is no separate package for -pyray. Do not pip install pyray). You can use either or both:

+

How to use

+

There are two APIs, you can use either or both:

-

If you are familiar with C coding and the Raylib C library and you want to use an exact copy of the C API

-

Use the raylib module.

+

If you are familiar with C coding and the Raylib C library and you want to use an exact copy of the C API

+

Use the C API.

-
-

If you prefer a more Pythonistic API

-

Use the pyray module.

+
+

If you prefer a slightly more Pythonistic API and don’t mind it might be slightly slower

+

Use the Python API.

-
-

Running in a web browser

-

Pygbag >=0.8.7 supports running in a web browser. Usually the latest git version -is recommended.

-

Make a folder my_project with a file main.py:

-
# /// script
-# dependencies = [
-#     "cffi",
-#     "raylib"
-# ]
-# ///
-import asyncio
-import platform
-from pyray import *
-
-async def main():   # You MUST have an async main function
-    init_window(500, 500, "Hello")
-    platform.window.window_resize()  # You MAY want to add this line
-    while not window_should_close():
-        begin_drawing()
-        clear_background(WHITE)
-        draw_text("Hello world", 190, 200, 20, VIOLET)
-        end_drawing()
-        await asyncio.sleep(0) # You MUST call this in your main loop
-    close_window()
-
-asyncio.run(main())
-
-
-

Then to create the web files and launch a web server:

-
python3.12 -m pip install --user --upgrade pygbag
-python3.12 -m pygbag --PYBUILD 3.12 --ume_block 0 --template noctx.tmpl --git my_project
-
-
-

Point your browser to http://localhost:8000

-

Some features may not work, so you can disable them like this:

-
if platform.system() != "Emscripten":  # audio may not work on current version of emscripten
-    init_audio_device()
-
-
-

This is all done by Pygbag rather than by me, so you should probably contact them with any issues. -Carefully read all their documentation.

-

It does work for most of these examples

-
-

App showcase

-

Tempest-raylib

-

KarabinerKeyboard

-

PyTaiko

-

DOOM-Clone

+

App showcase

Tanki

Alloy Bloxel Editor

-

Eidolon

Add your app here!

-

RLZero

+

RLZero

A related library (that is a work in progress!):

A simplified API for Raylib for use in education and to enable beginners to create 3d games

-

Help wanted

+

Help wanted

  • Converting more examples from C to Python

  • Testing on more platforms

-
-

License

-

Eclipse Public License, so you are free to +

+

License (updated)

+

The bindings are now under the Eclipse Public License, so you are free to statically link and use in non-free / proprietary / commercial projects!

-

Performance

-

If you need more performance, do in this order:

-
    -

  1. Use Pypy rather than standard CPython. It is much, much faster and will make more difference than any other optimisations you might do.

    2. -

  2. Every call to C is costly, so it’s slightly faster if you use Python data structures and functions when calculating +

    Performance

    +

    For fastest performance use Pypy rather than standard Python.

    +

    Every call to C is costly, so it’s slightly faster if you use Python data structures and functions when calculating in your update loop -and then only convert them to C data structures when you have to call the C functions for drawing.

    3. -

  3. The raylib.* functions are potentially slightly faster than the pyray.* equivalents, so if you need a tiny bit more performance -you can switch your inner loop functions to these.

    4. -

  4. There is a version of Python that is faster than Pypy: GraalPy. However it’s not fully compatible with all Python -packages. It doesn’t work with CFFI and so doesn’t work with this binding. But it is compatible with the -Java binding, Jaylib! There is an example of this here: https://github.com/electronstudio/megabunny/tree/master/raylib-python-jaylib

    5. -
+and then only convert them to C data structures when you have to call the C functions for drawing.

-

Bunnymark

- +

Bunnymark

+
@@ -354,53 +215,37 @@ packages. It doesn’t work with CFFI and so doesn’t work with this binding. - - - - - - - - - - - - - - - - + - + - + - + - +

Library

Implementation

Raylib 5.0

C

180000

100%

Raylib Python CFFI 5.0.0.2

Python 3.12

10500

5.8%

Raylib Python CFFI 5.0.0.2

Pypy 3.10

95000

53%

Raylib 3.7

Raylib 3.7

C

168100

100%

Raylib Python CFFI 3.7

Raylib Python CFFI 3.7

Pypy 3.7

33800

20%

Raylib Python CFFI 3.7

Raylib Python CFFI 3.7

Python 3.9

7700

4.5%

Raylib Python CFFI 3.7

Raylib Python CFFI 3.7

Python 3.9 Nuitka

8600

5.1%

Raylib Python CFFI 3.7 Dynamic

Raylib Python CFFI 3.7 Dynamic

Python 3.9

6300

3.7%
-

See also https://github.com/electronstudio/megabunny/

-

Packaging your app

+

Packaging your app

You can create a standalone binary using the Nuitka compiler. For example, here is how to package Bunnymark:

pip3 install nuitka
 cd examples/textures
@@ -409,7 +254,7 @@ python3 -m nuitka --onefile --linux-onefile-icon resources/wabbit_alpha.png text