Skip to content
Go to file


Failed to load latest commit information.
Latest commit message
Commit time
Dec 22, 2017
Jan 14, 2017
Sep 13, 2020


Azure DevOps tests Code style: black

Godot Python, because you want Python on Godot !

The goal of this project is to provide Python language support as a scripting module for the Godot game engine.


By order of simplicity:

  • Directly download the project from within Godot with the asset library tab.
  • Download from the asset library website.
  • Finally you can also head to the project release page if you want to only download one specific platform build



# Explicit is better than implicit
from godot import exposed, export, Vector2, Node2D, ResourceLoader

WEAPON_RES = ResourceLoader.load("res://weapon.tscn")
SPEED = Vector2(10, 10)

class Player(Node2D):
        This is the file's main class which will be made available to Godot. This
        class must inherit from `godot.Node` or any of its children (e.g.

        Because Godot scripts only accept file paths, you can't have two `exposed` classes in the same file.
        # Exposed class can define some attributes as export(<type>) to achieve
        # similar goal than GDSscript's `export` keyword
        name = export(str)

        # Can export property as well
        def age(self):
                return self._age

        def age(self, value):
                self._age = value

        # All methods are exposed to Godot
        def talk(self, msg):
                print(f"I'm saying {msg}")

        def _ready(self):
                # Don't confuse `__init__` with Godot's `_ready`!
                self.weapon = WEAPON_RES.instance()
                self._age = 42
                # Of course you can access property & methods defined in the parent
                name = self.get_name()
                print(f"{name} position x={self.position.x}, y={self.position.y}")

        def _process(self, delta):
                self.position += SPEED * delta


class Helper:
        Other classes are considered helpers and cannot be called from outside
        Python. However they can be imported from another python module.


To build the project from source, first checkout the repo or download the latest tarball.

Godot-Python requires Python >= 3.7 and a C compiler.

Godot GDNative header

The Godot GDNative headers are provided as git submodule:

$ git submodule init
$ git submodule update

Alternatively, you can get them from github.


On a fresh Ubuntu install, you will need to install these:

$ apt install python3 python3-pip python3-venv build-essential

On top of that build the CPython interpreter requires development headers of it extension modules (for instance if you lack sqlite dev headers, your Godot-Python build won't contain the sqlite3 python module)

The simplest way is to uncomment the main deb-src in /etc/apt/sources.list:

deb-src artful main

and instruct apt to install the needed packages:

$ apt update
$ apt build-dep python3.6

See the Python Developer's Guide for instructions on additional platforms.


With MacOS, you will need XCode installed and install the command line tools.

$ xcode-select --install

If you are using CPython as your backend, you will need these. To install with Homebrew:

$ brew install python3 openssl zlib

You will also need virtualenv for your python.


Install VisualStudio and Python3, then submit a PR to improve this paragraph ;-)

Create the virtual env

Godot-Python build system is heavily based on Python (mainly Scons, Cython and Jinja2). Hence we have to create a Python virtual env to install all those dependencies without clashing with your global Python configuration.

$ cd <godot-python-dir>
godot-python$ python3 -m venv venv

Now you need to activate the virtual env, this is something you should do every time you want to use the virtual env.

For Linux/MacOS:

godot-python$ . ./venv/bin/activate

For Windows:

godot-python$ ./venv/bin/activate.bat

Finally we can install dependencies:

godot-python(venv)$ pip install -r requirements.txt

Running the build

For Linux:

godot-python(venv)$ scons platform=x11-64 release

For Windows:

godot-python(venv)$ scons platform=windows-64 release

For MacOS:

godot-python(venv)$ scons platform=osx-64 CC=clang release

Valid platforms are x11-64, x11-32, windows-64, windows-32 and osx-64. Check Travis or Appveyor links above to see the current status of your platform.

This command will checkout CPython repo, move to a pinned commit and build CPython from source.

It will then generate pythonscript/godot/bindings.pyx (Godot api bindings) from GDNative's api.json and compile it. This part is long and really memory demanding so be patient ;-) When hacking godot-python you can heavily speedup this step by passing sample=true to scons in order to build only a small subset of the bindings.

Eventually the rest of the source will be compiled and a zip build archive will be available in the build directory.

Testing your build

godot-python(venv)$ scons platform=<platform> test

This will run pytests defined in tests/bindings inside the Godot environment. If not present, will download a precompiled Godot binary (defined in SConstruct and platform specific SCSub files) to and set the correct library path for the GDNative wrapper.

Running the example project

godot-python(venv)$ scons platform=<platform> example

This will run the converted pong example in examples/pong inside the Godot environment. If not present, will download a precompiled Godot binary (defined in SConstruct) to and set the correct library path for the GDNative wrapper.

Using a local Godot version

If you have a pre-existing version of godot, you can instruct the build script to use that the static library and binary for building and tests.

godot-python(venv)$ scons platform=x11-64 godot_binary=../godot/bin/godot.x11.opt.64

Additional build options

You check out all the build options in this file.


How can I export my project?

See this issue.

How can I debug my project with PyCharm?

This can be done using "Attach to Local Process", but first you have to change the Godot binary filename to include python, for example Godot_v3.0.2-stable_win64.exe to python_Godot_v3.0.2-stable_win64.exe. For more detailed guide and explanation see this external blog post.

How can I autoload a python script without attaching it to a Node?

In your project.godot file, add the following section:


In addition to the usual:

singletons=[ "res://pythonscript.gdnlib" ]

You can use any name for the python file and the class name autoloadpy.

Then can expose a Node:

from godot import exposed, export
from godot.bindings import *

class autoload(Node):

    def hi(self, to):
        return 'Hello %s from Python !' % to

which can then be called from your gdscript code as an attribute of the autoloadpy class (use the name defined in your project.godot):


How can I efficiently access PoolArrays?

PoolIntArray, PoolFloatArray, PoolVector3Array and the other pool arrays can't be accessed directly because they must be locked in memory first. Use the arr.raw_access() context manager to lock it:

arr = PoolIntArray() # create the array

with arr.raw_access() as ptr:
    for i in range(10000):
        ptr[i] = i # this is fast

# read access:
with arr.raw_access() as ptr:
    for i in range(10000):
        assert ptr[i] == i # so is this

Keep in mind great performances comes with great responsabilities: there is no boundary check so you may end up with memory corruption if you don't take care ;-)

See the godot-python issue.


Python support for Godot 🐍🐍🐍





No packages published


You can’t perform that action at this time.