developer.gnome.org

What is GNOME Development?

GNOME Development is the official entry point for building applications for the GNOME desktop environment. It gathers the human interface guidelines, recommended tools, packaging method and learning resources that GNOME itself points developers toward, rather than being a single product or SDK download.

What the site covers

• Design: The GNOME Human Interface Guidelines (HIG) set out design principles, conventions and resources for creating apps that look and behave consistently within GNOME.
• Build: Builder is presented as an IDE tailored to GNOME app development, with deep integration for GTK, Flatpak and other GNOME tools.
• Distribute: Flatpak is the recommended distribution format, offering sandboxed, cross-distribution compatibility on Linux with an emphasis on security and consistency.
• Learn: Resources cover the technologies behind GNOME development, from core building blocks to developer documentation and tutorials.
• Community: A discussion platform connects you with other GNOME developers for questions and collaboration. Donations support development infrastructure, community events and Flathub.

Who it is for

It suits developers targeting the GNOME desktop or Linux more broadly, especially those new to GTK and Flatpak who want an officially guided path. If you already know GTK well, the HIG and Flatpak guidance remain the most useful parts; the tooling pages are more of a starting point.

A practical first step

Pick a small app idea, read the HIG section that matches its main screen, then set up Builder and package an early build as a Flatpak. That sequence forces you through design, code and distribution before you commit to a larger project. For broader desktop work, KDE and Flathub are useful comparisons for toolkit conventions and app availability.

How do I start building a GNOME app with Builder?

Start by installing GNOME Builder, then let it scaffold a project for you rather than creating files by hand. Builder is the IDE the GNOME project points developers to, and it is built specifically around the GNOME stack: GTK for the interface, Flatpak for packaging and sandboxing, and the wider GNOME developer tooling. That integration is the main reason to use it over a general-purpose editor — you get templates, build configuration and a runnable app without assembling the toolchain yourself.

The practical order of work looks like this:

1. Read the design guidance first. The GNOME Human Interface Guidelines (HIG) cover layout conventions and interaction patterns. Skimming them before writing UI code saves rework, because GNOME apps are expected to feel consistent with the rest of the desktop.
2. Create a new project in Builder. Use its project templates to pick a language and app type. This generates the source tree, build files and a minimal window you can run immediately.
3. Run and iterate inside the IDE. Builder builds and launches the app in a development environment, so you can change code and see the result without leaving the editor.
4. Package with Flatpak. Flatpak is the distribution format GNOME promotes: a sandboxed bundle that works across Linux distributions and gives users consistent permissions and security behaviour.
5. Ask when stuck. GNOME's discussion platform is where developers raise questions and compare approaches with others working on the same stack.

Choosing your language

The GNOME developer documentation lists multiple supported languages, so the choice is mostly about what you already know and what you want to maintain.

Builder's templates cover more than one language, so you are not locked in by opening the IDE. If you are unsure, pick the language whose GNOME tutorials you find easiest to follow — the framework concepts (widgets, signals, application lifecycle) transfer between them.

A concrete first target

Build something small enough to finish in an afternoon: a single-window app with a header bar, one list or text view, and a settings toggle that persists between launches. That exercises the parts you will use in every real project — window structure, GTK widgets, application state — without the distraction of a large feature set. Once it runs, package it as a Flatpak and install it on your own machine; that step surfaces manifest and permission problems early, when they are cheap to fix.

For reference material beyond the IDE, the GNOME developer documentation is the primary source, and GNOME GitLab hosts the source of GNOME apps you can read as working examples. The GTK project's own site, GTK, documents the toolkit itself when you need widget-level detail rather than app-level guidance.

What are the GNOME Human Interface Guidelines and why should I follow them?

The GNOME Human Interface Guidelines (HIG) are GNOME's official design reference: a set of principles, conventions, and reusable patterns for building applications that look and behave like native GNOME apps. They cover the decisions you make before and while writing code — layout, navigation, controls, wording, and how your app should respond to different window sizes and input methods. The GNOME Development site points to the HIG as the starting point for design, alongside the tools and technologies used to build and ship apps.

Why following them pays off

• Consistency for users. GNOME users already know how header bars, sidebars, and standard dialogs work. Matching those conventions means less relearning and fewer surprises.
• Less design work. The HIG supplies established patterns, so you spend time on your app's specific problem instead of reinventing basic navigation or settings.
• Better fit with the platform. GNOME apps are expected to adapt to different window sizes and to work well with keyboard, mouse, and touch. The guidelines describe how to handle those cases.
• Smoother review and distribution. Apps intended for the GNOME ecosystem and Flathub are more likely to meet expectations when they follow platform conventions.

A practical way to use them

Start with the HIG before you settle on a layout, not after the UI is built. Sketch your main window and navigation using the recommended patterns, then check the guidelines again when you add dialogs, empty states, and preferences. If you are new to the stack, pair the HIG with the GNOME Development resources on building with Builder and distributing through Flatpak, so design and packaging decisions stay aligned.

For a concrete example: an app with a list of items and a detail view should use a split view that collapses sensibly on narrow windows, rather than a fixed two-column layout. The HIG explains when that pattern is appropriate and how it should behave.

When to deviate

The guidelines are conventions, not hard rules. If your app has a genuinely unusual interaction — a drawing canvas, a game, a specialized editor — follow the spirit (predictable navigation, clear labels, accessible controls) while adapting the specifics. Document your reasoning so contributors and reviewers understand the choice.

To go further, read the HIG directly and compare your app against a well-established GNOME application in the same category.

How do I distribute my GNOME app using Flatpak?

Flatpak is the recommended distribution route for GNOME apps. It packages your application with its runtime dependencies into a sandboxed bundle that runs across Linux distributions, so you build and test once rather than chasing per-distro packaging. GNOME's own developer resources point to Flatpak as the universal distribution format for Linux apps, alongside Builder as the IDE with deep integration for GTK, Flatpak and GNOME tooling.

The practical path

1. Finish the app first. Get it building and running locally with GTK and your chosen language bindings before you think about packaging.
2. Write a manifest. A Flatpak manifest is a small file describing your app, its runtime (for example a GNOME runtime), its dependencies and how to build it. This is the core artifact you maintain.
3. Build and test locally. Use Builder or the flatpak-builder tooling to produce a build, then run it in the sandbox and check that file access, portals, fonts, icons and settings all behave.
4. Handle sandbox permissions deliberately. Flatpak apps are sandboxed, so anything touching the network, filesystem, devices or the session bus needs a declared permission. Ask for the minimum; broad permissions invite user distrust and review friction.
5. Publish to Flathub. Flathub is the main catalog Linux users browse, and GNOME's page notes that donations help keep it running. Submitting means hosting a manifest repository and going through Flathub's review, which checks build reproducibility, metadata and permissions.
6. Ship updates. Once published, new releases flow to users through the store rather than through distro release cycles.

Where the trade-offs are

A concrete scenario: you maintain a small GTK notes app and want it in front of users on Fedora, Ubuntu and Arch without maintaining three packaging recipes. A Flatpak manifest plus a Flathub listing gets you there, and you spend your release time on the app instead of on spec files.

Next step

Read the GNOME developer documentation on Flatpak and the human interface guidelines before you finalise your manifest — the HIG shapes what your app should look like, and the Flatpak docs shape how it gets delivered. For general Linux packaging context, Flatpak and Flathub are the official references, and GNOME GitLab is where GNOME projects and issues live.

Decision criterion: if your users are on multiple distributions or you want sandboxed, consistent behaviour, Flatpak is the default. If you are targeting a single distribution's repositories or need deep system integration, distro packaging may still be worth the extra work.

Where can I ask questions and get help from other GNOME developers?

Ask on GNOME's own discussion platform, which the developer site points to under "Talk to Us." That is the official place for questions and conversation with other GNOME developers, and it's the first stop for design, build and distribution problems.

What to expect and how to use it

The page groups its guidance into four areas, and matching your question to the right one usually gets a faster, more useful reply:

A practical pattern for a new contributor: read the HIG or a tutorial first, try the thing in Builder, then post a specific question with your code, error output, and what you already tried. Vague "how do I build a GNOME app" posts tend to stall; a post showing the exact step that failed tends to get answered quickly.

Wider places to look

• GNOME Discourse — the discussion platform referenced for asking questions and talking to other developers.
• GNOME GitLab — issue trackers and merge requests for individual GNOME projects; good for bug reports and code-level questions.
• GNOME Development — the developer hub itself, with docs, tutorials and the "Talk to Us" links.

For a concrete scenario: if your GTK window misbehaves on one distro, search the forum and the project's issue tracker first, then post a minimal reproduction. You'll usually get an answer from a maintainer or another app developer within a day or two.

Why does GNOME need donations and what do they fund?

GNOME's donation appeal is tied directly to the infrastructure its developers rely on: the page states that donations fund improvements to development infrastructure, community events, and keeping Flathub running.

What donations are said to fund

• Development infrastructure — the build, hosting and tooling that contributors depend on to write and test GNOME software.
• Community events — gatherings that connect contributors and maintainers.
• Flathub — the app store and distribution service for Flatpak applications, which the page describes as central to shipping GNOME apps across Linux distributions.

Why this matters in practice

A developer packaging a GTK app with Flatpak depends on Flathub being available and reliable; if that service is donation-funded, the cost of distribution is shared across users and companies rather than charged per app. Similarly, shared infrastructure and events reduce the overhead for volunteers who contribute code without being paid by a single employer.

If you want to judge whether giving is worthwhile, check the linked areas rather than the appeal itself: look at the developer documentation for the tooling, the Flathub service, and GNOME's community channels, then decide which of those you actually use. Someone who only consumes apps might value Flathub; someone who builds them might value the infrastructure and events more. The page also notes that donations support hosting community events and keeping Flathub running, so a recurring contribution is the model implied rather than a one-off purchase.

For a broader view of the project beyond the developer portal, see GNOME and Flathub.