.. include:: icons.rst

.. _gettingstarted:

===============
Getting Started
===============

To get things started we will try to run a very simple `GTK
<https://www.gtk.org/>`_ based GUI application using the :doc:`PyGObject <index>` provided
Python bindings. First create a small Python script called ``hello.py`` with
the following content and save it somewhere:

.. code:: python

    import gi

    gi.require_version("Gtk", "4.0")
    from gi.repository import GLib, Gtk


    class MyApplication(Gtk.Application):
        def __init__(self):
            super().__init__(application_id="com.example.MyGtkApplication")
            GLib.set_application_name('My Gtk Application')

        def do_activate(self):
            window = Gtk.ApplicationWindow(application=self, title="Hello World")
            window.present()


    app = MyApplication()
    app.run()

Before we can run the example application we need to install PyGObject, GTK,
and their dependencies. Follow the instructions for your platform below or use
a cross-platform package manager like `conda <https://docs.conda.io/>`_ or
`Pixi <https://pixi.sh/>`_.

For full IDE support (incl. autocomplete) you will also need typing stubs
available here `PyGObject-stubs <https://pypi.org/project/PyGObject-stubs/>`_.

======================================================= ==================================================== ==========================================================
|ubuntu-logo| :ref:`Ubuntu <ubuntu-getting-started>`    |fedora-logo| :ref:`Fedora <fedora-getting-started>` |arch-logo| :ref:`Arch Linux <arch-getting-started>`
|windows-logo| :ref:`Windows <windows-getting-started>` |macosx-logo| :ref:`macOS <macosx-getting-started>`  |opensuse-logo| :ref:`openSUSE <opensuse-getting-started>`
|conda-logo| :ref:`Conda <conda-getting-started>`       |pixi-logo| :ref:`Pixi <pixi-getting-started>`       |source-logo| :ref:`from Source <devenv>`
======================================================= ==================================================== ==========================================================

After running the example application have a look at the :doc:`/tutorials/index`
for an overview of how to create GTK apps and the `GNOME Python API docs
<https://api.pygobject.gnome.org/>`__ for API documentation for all supported
libraries.


.. _windows-getting-started:

|windows-logo| Windows
----------------------

#) Go to https://www.msys2.org/ and download the x86_64 installer
#) Follow the instructions on the page for setting up the basic environment
#) Run ``C:\msys64\ucrt64.exe`` - a terminal window should pop up
#) Execute ``pacman -Suy``
#) Execute ``pacman -S mingw-w64-ucrt-x86_64-gtk4 mingw-w64-ucrt-x86_64-python mingw-w64-ucrt-x86_64-python-gobject``

   .. note::
      While some systems may use ``python3`` in the package name, current MSYS2 UCRT64
      environments typically use ``python``. If one fails, try the other (incl. step 8).
#) To test that GTK is working you can run ``gtk4-demo``
#) Copy the ``hello.py`` script you created to ``C:\msys64\home\<username>``
#) In the mingw32 terminal execute ``python hello.py`` - a window should appear.

.. figure:: images/start_windows.png
    :scale: 60%

NOTE: You will need to tell PyGObject where to search for DLLs by setting
`PYGI_DLL_PATH`, which takes a `;`-separated list of directories.

.. _ubuntu-getting-started:

|ubuntu-logo| Ubuntu / |debian-logo| Debian
-------------------------------------------

Installing the system provided PyGObject:
  #) Open a terminal
  #) Execute ``sudo apt install python3-gi python3-gi-cairo gir1.2-gtk-4.0``
  #) Change the directory to where your ``hello.py`` script can be found (e.g. ``cd Desktop``)
  #) Run ``python3 hello.py``

Installing from PyPI with pip:
  #) Open a terminal and enter your virtual environment
  #) Execute ``sudo apt install libgirepository-2.0-dev gcc libcairo2-dev pkg-config python3-dev gir1.2-gtk-4.0``
     to install the build dependencies and GTK
  #) Execute ``pip3 install pycairo`` to build and install Pycairo
  #) Execute ``pip3 install PyGObject`` to build and install PyGObject
  #) Change the working directory to where your ``hello.py`` script can be found
  #) Run ``python3 hello.py``

|start-linux|

.. _fedora-getting-started:

|fedora-logo| Fedora
--------------------

Installing the system provided PyGObject:
  #) Open a terminal
  #) Execute ``sudo dnf install python3-gobject gtk4``
  #) Change the working directory to where your ``hello.py`` script can be found
  #) Run ``python3 hello.py``

Installing from PyPI with pip:
  #) Open a terminal and enter your virtual environment
  #) Execute ``sudo dnf install gcc gobject-introspection-devel cairo-gobject-devel pkg-config python3-devel gtk4``
     to install the build dependencies and GTK
  #) Execute ``pip3 install pycairo`` to build and install Pycairo
  #) Execute ``pip3 install PyGObject`` to build and install PyGObject
  #) Change the working directory to where your ``hello.py`` script can be found
  #) Run ``python3 hello.py``


.. _arch-getting-started:

|arch-logo| Arch Linux
----------------------

Installing the system provided PyGObject:
  #) Open a terminal
  #) Execute ``sudo pacman -S python-gobject gtk4``
  #) Change the working directory to where your ``hello.py`` script can be found
  #) Run ``python3 hello.py``

Installing from PyPI with pip:
  #) Open a terminal and enter your virtual environment
  #) Execute ``sudo pacman -S python cairo pkgconf gobject-introspection gtk4``
     to install the build dependencies and GTK
  #) Execute ``pip3 install pycairo`` to build and install Pycairo
  #) Execute ``pip3 install PyGObject`` to build and install PyGObject
  #) Change the working directory to where your ``hello.py`` script can be found
  #) Run ``python3 hello.py``


.. _opensuse-getting-started:

|opensuse-logo| openSUSE
------------------------

Installing the system provided PyGObject:
  #) Open a terminal
  #) Execute ``sudo zypper install python3-gobject python3-gobject-Gdk typelib-1_0-Gtk-4_0 libgtk-4-1``
  #) Change the directory to where your ``hello.py`` script can be found
  #) Run ``python3 hello.py``

Installing from PyPI with pip:
  #) Open a terminal and enter your virtual environment
  #) Execute ``sudo zypper install cairo-devel pkg-config python3-devel gcc gobject-introspection-devel``
     to install the build dependencies and GTK
  #) Execute ``pip3 install pycairo`` to build and install Pycairo
  #) Execute ``pip3 install PyGObject`` to build and install PyGObject
  #) Change the working directory to where your ``hello.py`` script can be found
  #) Run ``python3 hello.py``


.. _macosx-getting-started:

|macosx-logo| macOS
-------------------

#) Go to https://brew.sh/ and install homebrew
#) Open a terminal
#) Execute ``brew install pygobject3 gtk4``
#) Change the working directory to where your ``hello.py`` script can be found
#) Run ``python3 hello.py``

.. figure:: images/start_macos.png
    :scale: 70%

.. _conda-getting-started:

|conda-logo| conda
------------------

#) Go to https://docs.conda.io and install Miniconda or Miniforge
#) Open a terminal
#) Execute ``conda create --channel conda-forge --name pygobject pygobject gtk4``
#) Execute ``conda activate pygobject``
#) Change the working directory to where your ``hello.py`` script can be found
#) Run ``python hello.py``

|start-conda|

.. _pixi-getting-started:

|pixi-logo| Pixi
----------------

#) Go to https://pixi.sh/latest/installation/ and install pixi
#) Place your ``hello.py`` script into a separate ``hello`` directory
#) Open a terminal and ``cd hello``
#) Execute ``pixi init .``
#) Execute ``pixi add pygobject gtk4``
#) Run ``pixi run python hello.py``

|start-pixi|

----

For more details on how to use a virtualenv with PyGObject, see the
":ref:`devenv`" page.

.. toctree::
    :hidden:
    :maxdepth: 1
    :caption: What's new

    news/pygobject-3-56

.. toctree::
    :hidden:
    :maxdepth: 1
    :caption: Project Information

    changelog
    bugs_repo