Skip to main content
`Ctrl`+`K`

# Creating a Development Environment

This describes how to setup a development environment for working on a project that uses PyGObject, or for working on PyGObject itself. Please follow the instructions on “Getting Started” first, as they are a pre-requirement.

## Environment Setup

### Install Dependencies

In order to compile Python and pip install pygobject, dependencies are need for your operating system.

Ubuntu | Fedora | Arch Linux
Windows | macOS | openSUSE

#### Ubuntu / Debian

    sudo apt-get install -y python3-venv python3-wheel python3-dev
    sudo apt-get install -y gobject-introspection libgirepository-2.0-dev \
      gir1.2-girepository-3.0 build-essential libbz2-dev libreadline-dev \
      libssl-dev zlib1g-dev libsqlite3-dev wget curl llvm libncurses-dev \
      xz-utils tk-dev libcairo2-dev

#### Fedora

    sudo dnf install -y python3-wheel
    sudo dnf install -y gcc zlib-devel bzip2 bzip2-devel readline-devel \
      sqlite sqlite-devel openssl-devel tk-devel git python3-cairo-devel \
      cairo-gobject-devel gobject-introspection-devel

#### Arch Linux

    sudo pacman -S --noconfirm python-wheel
    sudo pacman -S --noconfirm base-devel openssl zlib git gobject-introspection

#### openSUSE

    sudo zypper install -y python3-wheel gobject-introspection-devel \
      python3-cairo-devel openssl zlib git
    sudo zypper install --type pattern devel_basis

#### Windows

To develop on Windows you need to have MSYS2 installed.

    pacman -S --needed --noconfirm base-devel mingw-w64-ucrt-x86_64-toolchain git \
       mingw-w64-ucrt-x86_64-python mingw-w64-ucrt-x86_64-pycairo \
       mingw-w64-ucrt-x86_64-gobject-introspection mingw-w64-ucrt-x86_64-libffi

#### macOS

With homebrew:

    brew update
    brew install python3 gobject-introspection libffi
    export PKG_CONFIG_PATH=$(brew --prefix libffi)/lib/pkgconfig  # use /usr/local/ for older Homebrew installs

### Install pyenv (Optional)

pyenv lets you easily switch between multiple versions of Python.

Linux | macOS

#### Linux

    curl https://pyenv.run | bash
    exec $SHELL
    pyenv install 3.11
    pyenv global 3.11

#### macOS

    brew install pyenv
    pyenv install 3.11
    pyenv global 3.11

## Work on PyGObject

### Platform Independent Steps

First, check out the source code:

    git clone https://gitlab.gnome.org/GNOME/pygobject.git
    cd pygobject

With a local copy of PyGObject, there’s three ways to start developing:

1. PDM, a modern Python package and dependency manager

2. Pip, the default Python package installer

3. Meson, use the Meson build system directly

#### PDM

Make sure you have PDM 2.13 or newer installed.

Then set up the project by running:

    pdm install

You can run the unit tests with:

    pdm run pytest

#### Pip

It’s always a good idea to work from within a Python virtual environment. PyGObject is built with Meson. In order to support editable installs, Meson-python, Meson, and Ninja should be installed in the virtual environment.

    python3 -m venv .venv
    source .venv/bin/activate
    python3 -m pip install meson-python meson ninja pycairo pytest pre-commit

Note

For Python 3.12 and newer, also install `setuptools`, since distutils is no longer provided in the standard library.

Install PyGObject in your local environment with the `--no-build-isolation` to allow for dynamic rebuilds

    pip install --no-build-isolation --config-settings=setup-args="-Dtests=true" -e '.[dev]'

By default the C libraries are built in “release” mode (no debug symbols). To compile the C libraries with debug symbols, run

    pip install --no-build-isolation --config-settings=setup-args="-Dbuildtype=debug" --config-settings=setup-args="-Dtests=true" -e '.[dev]'

Open a Python console:

    from gi.repository import GObject

Run the unittests:

    pytest

#### Meson

It’s also possible to run the tests from Meson. Tests are still run with Pytest, so it’s important that Pytest is installed.

    meson setup _build  # Needed only once
    meson test -C _build

### Contributing Changes

First off, thank you for considering contributing to PyGObject. We really appreciate it!

- Create your own fork of the repository

- Add tests for your changes

- Do the changes in your fork

- If you like the change and think the project could use it:

  - Make sure you are following the GNOME Code of Conduct

  - Be sure you have the pre-commit hook installed with:

        pre-commit install

    It will ensure that lint and code formatting tools are run automatically.

  - Commit your changes

  - Create a merge request