This repository has been archived on 2025-06-21. You can view files and clone it, but you cannot make any changes to it's state, such as pushing and creating new issues, pull requests or comments.
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
<!DOCTYPE html>
<html class="writer-html5" lang="en" data-content_root="./">
<head>
<meta charset="utf-8" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Python Bindings for Raylib 5.5 — Raylib Python documentation</title>
<link rel="stylesheet" type="text/css" href="_static/pygments.css?v=fa44fd50" />
<link rel="stylesheet" type="text/css" href="_static/css/theme.css?v=e59714d7" />
<link rel="stylesheet" type="text/css" href="_static/graphviz.css?v=4ae1632d" />
<script src="_static/jquery.js?v=5d32c60e"></script>
<script src="_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
<script src="_static/documentation_options.js?v=5929fcd5"></script>
<script src="_static/doctools.js?v=9bcbadda"></script>
<script src="_static/sphinx_highlight.js?v=dc90522c"></script>
<script src="_static/js/theme.js"></script>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="Python API" href="pyray.html" />
<link rel="prev" title="Raylib Python" href="index.html" />
</head>
<body class="wy-body-for-nav">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-scroll">
<div class="wy-side-nav-search" >
<a href="index.html" class="icon icon-home">
Raylib Python
</a>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="search.html" method="get">
<input type="text" name="q" placeholder="Search docs" aria-label="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
<p class="caption" role="heading"><span class="caption-text">Contents:</span></p>
<ul class="current">
<li class="toctree-l1 current"><a class="current reference internal" href="#">Python Bindings for Raylib 5.5</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#libraries-raymath-raygui-rlgl-physac-and-glfw">Libraries: raymath, raygui, rlgl, physac and GLFW</a></li>
<li class="toctree-l2"><a class="reference internal" href="#backends-desktop-sdl-drm-web">Backends: Desktop, SDL, DRM, Web</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="#quickstart">Quickstart</a></li>
<li class="toctree-l1"><a class="reference internal" href="#installation">Installation</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#windows">Windows</a></li>
<li class="toctree-l2"><a class="reference internal" href="#macos">MacOS</a></li>
<li class="toctree-l2"><a class="reference internal" href="#linux">Linux</a></li>
<li class="toctree-l2"><a class="reference internal" href="#raspberry-pi">Raspberry Pi</a></li>
<li class="toctree-l2"><a class="reference internal" href="#dynamic-binding-version">Dynamic binding version</a></li>
<li class="toctree-l2"><a class="reference internal" href="#sdl-backend">SDL backend</a></li>
<li class="toctree-l2"><a class="reference internal" href="#drm-backend">DRM backend</a></li>
<li class="toctree-l2"><a class="reference internal" href="#problems">Problems?</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="#how-to-use">How to use</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#if-you-are-familiar-with-c-coding-and-the-raylib-c-library-and-you-want-to-use-an-exact-copy-of-the-c-api">If you are familiar with C coding and the Raylib C library and you want to use an exact copy of the C API</a></li>
<li class="toctree-l2"><a class="reference internal" href="#if-you-prefer-a-more-pythonistic-api">If you prefer a more Pythonistic API</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="#running-in-a-web-browser">Running in a web browser</a></li>
<li class="toctree-l1"><a class="reference internal" href="#app-showcase">App showcase</a></li>
<li class="toctree-l1"><a class="reference internal" href="#rlzero">RLZero</a></li>
<li class="toctree-l1"><a class="reference internal" href="#help-wanted">Help wanted</a></li>
<li class="toctree-l1"><a class="reference internal" href="#license">License</a></li>
<li class="toctree-l1"><a class="reference internal" href="#performance">Performance</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#bunnymark">Bunnymark</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="#packaging-your-app">Packaging your app</a></li>
<li class="toctree-l1"><a class="reference internal" href="#advert">Advert</a></li>
<li class="toctree-l1"><a class="reference internal" href="pyray.html">Python API</a></li>
<li class="toctree-l1"><a class="reference internal" href="raylib.html">C API</a></li>
<li class="toctree-l1"><a class="reference internal" href="dynamic.html">Dynamic Bindings</a></li>
<li class="toctree-l1"><a class="reference internal" href="BUILDING.html">Building from source</a></li>
<li class="toctree-l1"><a class="reference internal" href="RPI.html">Raspberry Pi</a></li>
</ul>
</div>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" >
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="index.html">Raylib Python</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="Page navigation">
<ul class="wy-breadcrumbs">
<li><a href="index.html" class="icon icon-home" aria-label="Home"></a></li>
<li class="breadcrumb-item active">Python Bindings for Raylib 5.5</li>
<li class="wy-breadcrumbs-aside">
<a href="_sources/README.md.txt" rel="nofollow"> View page source</a>
</li>
</ul>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<section id="python-bindings-for-raylib-5-5">
<h1>Python Bindings for Raylib 5.5<a class="headerlink" href="#python-bindings-for-raylib-5-5" title="Link to this heading"></a></h1>
<section id="libraries-raymath-raygui-rlgl-physac-and-glfw">
<h2>Libraries: raymath, raygui, rlgl, physac and GLFW<a class="headerlink" href="#libraries-raymath-raygui-rlgl-physac-and-glfw" title="Link to this heading"></a></h2>
</section>
<section id="backends-desktop-sdl-drm-web">
<h2>Backends: Desktop, SDL, DRM, Web<a class="headerlink" href="#backends-desktop-sdl-drm-web" title="Link to this heading"></a></h2>
<p>Chatroom: <a class="reference external" href="https://discord.gg/fKDwt85aX6">Discord</a></p>
<p>New CFFI API static bindings.</p>
<ul class="simple">
<li><p>Automatically generated to be as close as possible to
original Raylib.</p></li>
<li><p>Faster, fewer bugs and easier to maintain than ctypes.</p></li>
<li><p>Commercial-friendly license.</p></li>
<li><p>Docstrings and auto-completion.</p></li>
</ul>
<p><a class="reference external" href="http://electronstudio.github.io/raylib-python-cffi">Full documentation</a></p>
</section>
</section>
<section id="quickstart">
<h1>Quickstart<a class="headerlink" href="#quickstart" title="Link to this heading"></a></h1>
<p><code class="docutils literal notranslate"><span class="pre">pip3</span> <span class="pre">install</span> <span class="pre">raylib==5.0.0.4</span></code></p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">pyray</span> <span class="kn">import</span> <span class="o">*</span>
<span class="n">init_window</span><span class="p">(</span><span class="mi">800</span><span class="p">,</span> <span class="mi">450</span><span class="p">,</span> <span class="s2">"Hello"</span><span class="p">)</span>
<span class="k">while</span> <span class="ow">not</span> <span class="n">window_should_close</span><span class="p">():</span>
<span class="n">begin_drawing</span><span class="p">()</span>
<span class="n">clear_background</span><span class="p">(</span><span class="n">WHITE</span><span class="p">)</span>
<span class="n">draw_text</span><span class="p">(</span><span class="s2">"Hello world"</span><span class="p">,</span> <span class="mi">190</span><span class="p">,</span> <span class="mi">200</span><span class="p">,</span> <span class="mi">20</span><span class="p">,</span> <span class="n">VIOLET</span><span class="p">)</span>
<span class="n">end_drawing</span><span class="p">()</span>
<span class="n">close_window</span><span class="p">()</span>
</pre></div>
</div>
</section>
<section id="installation">
<h1>Installation<a class="headerlink" href="#installation" title="Link to this heading"></a></h1>
<p>First make sure you have the latest pip installed:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>python3 -m pip install --upgrade pip
</pre></div>
</div>
<p>Then install</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>python3 -m pip install setuptools
python3 -m pip install raylib==5.0.0.4
</pre></div>
</div>
<p>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.
using homebrew, apt, etc.</p>
<section id="windows">
<h2>Windows<a class="headerlink" href="#windows" title="Link to this heading"></a></h2>
<p>Binaries require x64 Windows 10 or newer. (For x86 or older Windows you will have to build from source.)</p>
<p>Use an <a class="reference external" href="https://www.python.org/downloads/windows/">official Windows Python release</a> rather than WSL, MSYS, etc.</p>
</section>
<section id="macos">
<h2>MacOS<a class="headerlink" href="#macos" title="Link to this heading"></a></h2>
<p>Binaries require:</p>
<ul class="simple">
<li><p>arm64 MacOS 14</p></li>
<li><p>x64 MacOS 10.13, or newer.</p></li>
</ul>
<p>Older MacOS requires building from source but this is usually simple:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>brew install pkg-config
brew install raylib
python3 -m pip install raylib==5.0.0.4
</pre></div>
</div>
<p>(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.)</p>
</section>
<section id="linux">
<h2>Linux<a class="headerlink" href="#linux" title="Link to this heading"></a></h2>
<p>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.)</p>
<p>The arm64 binaries are built on Raspberry Pi arm64 Bullseye with OpenGL 2.0
so may not work on other boards.</p>
</section>
<section id="raspberry-pi">
<h2>Raspberry Pi<a class="headerlink" href="#raspberry-pi" title="Link to this heading"></a></h2>
<p><a class="reference internal" href="RPI.html"><span class="std std-doc">Using on Rasperry Pi</span></a></p>
</section>
<section id="dynamic-binding-version">
<h2>Dynamic binding version<a class="headerlink" href="#dynamic-binding-version" title="Link to this heading"></a></h2>
<p>There is now a separate dynamic version of this binding:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>python3 -m pip uninstall raylib
python3 -m pip install raylib_dynamic
</pre></div>
</div>
<p>It works on some systems where the static version doesn’t, <a class="reference external" href="https://electronstudio.github.io/raylib-python-cffi/dynamic.html">but be sure to read these caveats before using it</a></p>
</section>
<section id="sdl-backend">
<h2>SDL backend<a class="headerlink" href="#sdl-backend" title="Link to this heading"></a></h2>
<p>This is not well tested but has better support for controllers:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>python3 -m pip uninstall raylib
python3 -m pip install raylib_sdl
</pre></div>
</div>
<p>You can’t have multiple raylib packages installed at once.</p>
</section>
<section id="drm-backend">
<h2>DRM backend<a class="headerlink" href="#drm-backend" title="Link to this heading"></a></h2>
<p>This uses the Linux framebuffer for devices that don’t run X11/Wayland:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>python3 -m pip uninstall raylib
python3 -m pip install raylib_drm
</pre></div>
</div>
<p>You can’t have multiple raylib packages installed at once.</p>
</section>
<section id="problems">
<h2>Problems?<a class="headerlink" href="#problems" title="Link to this heading"></a></h2>
<p>If it doesn’t work, <a class="reference internal" href="BUILDING.html"><span class="std std-doc">try to build manually.</span></a>. If that works then <a class="reference external" href="https://github.com/electronstudio/raylib-python-cffi/issues">submit an issue</a>
to let us know what you did.</p>
<p>If you need help you can try asking on <a class="reference external" href="https://discord.gg/fKDwt85aX6">our discord</a>. There is also a large <a class="reference external" href="https://discord.gg/raylib">Raylib discord</a>
for issues that are not Python-specific.</p>
<p>If it still doesn’t work, <a class="reference external" href="https://github.com/electronstudio/raylib-python-cffi/issues">submit an issue</a>.</p>
</section>
</section>
<section id="how-to-use">
<h1>How to use<a class="headerlink" href="#how-to-use" title="Link to this heading"></a></h1>
<p>There are two modules in the raylib package, <code class="docutils literal notranslate"><span class="pre">raylib</span></code> and <code class="docutils literal notranslate"><span class="pre">pyray</span></code>. (There is no separate package for
pyray). You can use either or both:</p>
<section id="if-you-are-familiar-with-c-coding-and-the-raylib-c-library-and-you-want-to-use-an-exact-copy-of-the-c-api">
<h2>If you are familiar with C coding and the Raylib C library and you want to use an exact copy of the C API<a class="headerlink" href="#if-you-are-familiar-with-c-coding-and-the-raylib-c-library-and-you-want-to-use-an-exact-copy-of-the-c-api" title="Link to this heading"></a></h2>
<p>Use <a class="reference external" href="https://electronstudio.github.io/raylib-python-cffi/raylib.html">the raylib module</a>.</p>
</section>
<section id="if-you-prefer-a-more-pythonistic-api">
<h2>If you prefer a more Pythonistic API<a class="headerlink" href="#if-you-prefer-a-more-pythonistic-api" title="Link to this heading"></a></h2>
<p>Use <a class="reference external" href="https://electronstudio.github.io/raylib-python-cffi/pyray.html">the pyray module</a>.</p>
</section>
</section>
<section id="running-in-a-web-browser">
<h1>Running in a web browser<a class="headerlink" href="#running-in-a-web-browser" title="Link to this heading"></a></h1>
<p><a class="reference external" href="https://pypi.org/project/pygbag/">Pygbag</a> >=0.8.7 supports running in a web browser.</p>
<p>Make a folder <code class="docutils literal notranslate"><span class="pre">my_project</span></code> with a file <code class="docutils literal notranslate"><span class="pre">main.py</span></code>:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span># /// 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 must 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())
</pre></div>
</div>
<p>Then to create the web files and launch a web server:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>python3.12 -m pip install --user --upgrade pygbag
python3.12 -m pygbag --PYBUILD 3.12 --ume_block 0 --template noctx.tmpl my_project
</pre></div>
</div>
<p>Point your browser to http://localhost:8000</p>
<p>This is all done by Pygbag rather than by me, so you should probably contact them with any issues.
Carefully read all their <a class="reference external" href="https://pygame-web.github.io/">documentation</a>.</p>
<p>It does work for most of <a class="reference external" href="https://electronstudio.github.io/raylib-python-cffi-pygbag-examples/">these examples</a></p>
</section>
<section id="app-showcase">
<h1>App showcase<a class="headerlink" href="#app-showcase" title="Link to this heading"></a></h1>
<p><a class="reference external" href="https://github.com/pkulev/tanki">Tanki</a></p>
<p><a class="reference external" href="https://pebaz.itch.io/alloy-bloxel-editor">Alloy Bloxel Editor</a></p>
<p>Add your app here!</p>
</section>
<section id="rlzero">
<h1>RLZero<a class="headerlink" href="#rlzero" title="Link to this heading"></a></h1>
<p>A related library (that is a work in progress!):</p>
<p><a class="reference external" href="https://github.com/electronstudio/rlzero">A simplified API for Raylib for use in education and to enable beginners to create 3d games</a></p>
</section>
<section id="help-wanted">
<h1>Help wanted<a class="headerlink" href="#help-wanted" title="Link to this heading"></a></h1>
<ul class="simple">
<li><p>Converting more examples from C to Python</p></li>
<li><p>Testing on more platforms</p></li>
</ul>
</section>
<section id="license">
<h1>License<a class="headerlink" href="#license" title="Link to this heading"></a></h1>
<p>Eclipse Public License, so you are free to
statically link and use in non-free / proprietary / commercial projects!</p>
</section>
<section id="performance">
<h1>Performance<a class="headerlink" href="#performance" title="Link to this heading"></a></h1>
<p>If you need more performance, do in this order:</p>
<ol class="arabic simple">
<li><p>Use Pypy rather than standard CPython. It is much, much faster and will make more difference than any other optimisations you might do.</p></li>
<li><p>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.</p></li>
<li><p>The raylib.* functions are potentially <em>slightly</em> faster than the pyray.* equivalents, so if you need a tiny bit more performance
you can switch your inner loop functions to these.</p></li>
<li><p>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 <em>is</em> compatible with the
<em>Java</em> binding, Jaylib! There is an example of this here: https://github.com/electronstudio/megabunny/tree/master/raylib-python-jaylib</p></li>
</ol>
<section id="bunnymark">
<h2>Bunnymark<a class="headerlink" href="#bunnymark" title="Link to this heading"></a></h2>
<table class="docutils align-default">
<thead>
<tr class="row-odd"><th class="head"><p>Library</p></th>
<th class="head"><p>Implementation</p></th>
<th class="head"><p>Bunnies (60 FPS)</p></th>
<th class="head"><p>Percentage</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p>Raylib 5.0</p></td>
<td><p>C</p></td>
<td><p>180000</p></td>
<td><p>100%</p></td>
</tr>
<tr class="row-odd"><td><p>Raylib Python CFFI 5.0.0.2</p></td>
<td><p>Python 3.12</p></td>
<td><p>10500</p></td>
<td><p>5.8%</p></td>
</tr>
<tr class="row-even"><td><p>Raylib Python CFFI 5.0.0.2</p></td>
<td><p>Pypy 3.10</p></td>
<td><p>95000</p></td>
<td><p>53%</p></td>
</tr>
<tr class="row-odd"><td><p>Raylib 3.7</p></td>
<td><p>C</p></td>
<td><p>168100</p></td>
<td><p>100%</p></td>
</tr>
<tr class="row-even"><td><p>Raylib Python CFFI 3.7</p></td>
<td><p>Pypy 3.7</p></td>
<td><p>33800</p></td>
<td><p>20%</p></td>
</tr>
<tr class="row-odd"><td><p>Raylib Python CFFI 3.7</p></td>
<td><p>Python 3.9</p></td>
<td><p>7700</p></td>
<td><p>4.5%</p></td>
</tr>
<tr class="row-even"><td><p>Raylib Python CFFI 3.7</p></td>
<td><p>Python 3.9 Nuitka</p></td>
<td><p>8600</p></td>
<td><p>5.1%</p></td>
</tr>
<tr class="row-odd"><td><p>Raylib Python CFFI 3.7 Dynamic</p></td>
<td><p>Python 3.9</p></td>
<td><p>6300</p></td>
<td><p>3.7%</p></td>
</tr>
</tbody>
</table>
<p>See also https://github.com/electronstudio/megabunny/</p>
</section>
</section>
<section id="packaging-your-app">
<h1>Packaging your app<a class="headerlink" href="#packaging-your-app" title="Link to this heading"></a></h1>
<p>You can create a standalone binary using the Nuitka compiler. For example, here is how to package Bunnymark:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>pip3 install nuitka
cd examples/textures
python3 -m nuitka --onefile --linux-onefile-icon resources/wabbit_alpha.png textures_bunnymark.py
</pre></div>
</div>
</section>
<section id="advert">
<h1>Advert<a class="headerlink" href="#advert" title="Link to this heading"></a></h1>
<p><a class="reference external" href="https://store.steampowered.com/app/664240/RetroWar_8bit_Party_Battle/?git">RetroWar: 8-bit Party Battle</a> is out now. Defeat up to 15 of your friends in a tournament of 80s-inspired retro mini games.</p>
<p><a class="reference external" href="https://github.com/electronstudio/pygame-zero-book">Coding Games With Pygame Zero & Python</a> is
a book for Python beginners.</p>
</section>
</div>
</div>
<footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
<a href="index.html" class="btn btn-neutral float-left" title="Raylib Python" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
<a href="pyray.html" class="btn btn-neutral float-right" title="Python API" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
</div>
<hr/>
<div role="contentinfo">
<p>© Copyright 2021, Richard Smith.</p>
</div>
Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
<a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a>
provided by <a href="https://readthedocs.org">Read the Docs</a>.
</footer>
</div>
</div>
</section>
</div>
<script>
jQuery(function () {
SphinxRtdTheme.Navigation.enable(true);
});
</script>
</body>
</html>
