Ubuntu Start

An Ubuntu Desktop guide for first-run setup and device troubleshooting.

Swedish welcome screen · More screenshots

More screenshots: network diagnostics (EN) · audio status (EN) · Terminal guide (EN) · WiFi Analyzer recommendation (EN) · help page (EN) · hardware summary (EN)

Swedish system guides · network and hardware overview · network diagnostics · audio status · Terminal guide · WiFi Analyzer recommendation · help page · hardware summary · accessibility settings

Ubuntu Start combines a first-run guide with practical device troubleshooting for Ubuntu Desktop. It is a GTK 4/libadwaita application intended for Ubuntu GNOME.

Contributing

See CONTRIBUTING.md for contributor guidance and the maintainer pull request review process.

Current scope

• First steps for language, networking, updates, sound, display and privacy.
• Everyday tips for search, window management and Files, plus guidance on backups and choosing trusted app sources.
• Search device checks and step-by-step system guides together, then open a matching guide directly. Topics include sound, Bluetooth, batteries, printers, displays/graphics, keyboards, touchpads, Wi-Fi, Ethernet, cameras, accessibility and Terminal basics.
• Step-by-step guides for installing apps, updates, Wi-Fi, Ethernet, printers, batteries, keyboards, touchpads, larger text, screen magnification and the Orca screen reader.
• Accessibility guides explain larger text, zoom, screen reading, the on-screen keyboard, typing assistance and visual sound alerts, with plain-language steps before each change.
• A beginner-friendly Terminal guide explains the prompt, command output and errors, pwd, ls, cd, paths with spaces, Tab completion, command history, --help, man, sudo and safe ways to stop a command.
• Optional connection diagnostics report DNS lookup and gateway ping latency in milliseconds, plus the gateway MAC address and a local OUI vendor match. The test asks before running; it sends one DNS lookup to the configured resolver and one ping to the local gateway.
• Read-only Bluetooth status reports whether a controller is present and powered on without scanning for nearby devices.
• Read-only audio status checks the default speaker and microphone volume and mute state through PipeWire or PulseAudio without playing sounds or changing settings.
• Wi-Fi troubleshooting recommends WiFi Analyzer for nearby signal levels and channel use. Opening GitHub requires confirmation.
• Built-in links to official Ubuntu documentation, Ask Ubuntu and the Ubuntu support forum.
• Read-only NetworkManager, Bluetooth, hardware and storage summaries, battery charge and estimated capacity versus original design when exposed, plus a copyable support report that omits usernames, host names, serial numbers, network addresses, Wi-Fi names and installed applications.
• Links into GNOME Control Center and Ubuntu's Additional Drivers tool. System changes remain in Ubuntu's own tools and require the user's confirmation.
• gettext-based localization with English source strings and a complete Swedish (sv) catalog.

Build and run on Ubuntu

Install the platform dependencies, then build with Meson:

sudo apt install python3-gi gir1.2-gtk-4.0 gir1.2-adw-1 gettext meson ninja-build
meson setup build --prefix=/usr
meson compile -C build
sudo meson install -C build

To build an installable Debian package after installing the dependencies, run scripts/build-deb.sh. It creates build/packages/ubuntu-start_0.3.1-1_all.deb. Install it with sudo apt install ./build/packages/ubuntu-start_0.3.1-1_all.deb; APT resolves the declared GTK and Python runtime dependencies.

The PyPI wheel and source distribution are prepared. The initial upload needs a Trusted Publisher registered for this repository; after that, tagged releases publish automatically. Once the package is available, install the GTK platform dependencies with APT first, then install it in an isolated environment that can access system PyGObject bindings:

sudo apt install python3-gi gir1.2-gtk-4.0 gir1.2-adw-1 gettext
python3 -m venv --system-site-packages .venv
. .venv/bin/activate
python -m pip install ubuntu-start
ubuntu-start

For a source checkout, run python3 src/ubuntu_start.py to use the English source strings. To try the Swedish catalog from the checkout:

mkdir -p build/locale/sv/LC_MESSAGES
msgfmt po/sv.po -o build/locale/sv/LC_MESSAGES/ubuntu-start.mo
LANGUAGE=sv UBUNTU_START_LOCALEDIR="$PWD/build/locale" python3 src/ubuntu_start.py

Run the unit tests with PYTHONPATH=src python3 -m unittest discover -s tests -v. The CI workflow runs these tests and builds the app for pull requests.

NetworkManager, Bluetooth, audio, storage, battery and hardware summaries use local system information. DNS/gateway tests and the WiFi Analyzer GitHub link ask for confirmation before contacting an external service; DNS uses the configured resolver, ping targets the local gateway, and vendor matching uses a local OUI file when available. The separate internet test sends one HTTPS HEAD request to ubuntu.com after confirmation. Opening the Ubuntu App Center asks first because it may contact configured software sources; Ubuntu Start does not install apps. Other help pages open only when selected. No diagnostic report is uploaded, and serial numbers are not read. The app expects GTK 4, libadwaita and PyGObject.

Validation

Release v0.3.0 passed GitHub CI and the release workflow. The current 0.3.1 working tree passes all 41 unit tests, source-string coverage, translation checks, Python wheel/sdist builds and twine check. The 0.3.1 Debian package was built and installed on Ubuntu 26.10 machine trv2; package audit and APT dependency checks passed. A live GTK session exposed and verified a fix for search results with matching guides. Orca's AT-SPI app list detects Ubuntu Start. The network diagnostics remain unrun pending approval in the app's consent dialog. GNOME is selected as the next GDM session; TigerVNC currently uses Openbox because this Ubuntu image provides GNOME only as a Wayland session.

An earlier revision was also launched under Xvfb in English and Swedish. At that point PipeWire reported an unmuted default speaker at 100% and no default microphone. The GNOME Control Center panel list confirmed the Bluetooth, Wi-Fi, printer, display, privacy, sound and keyboard panel identifiers. The two Ubuntu driver/update utilities were installed with dpkg -i; Additional Drivers and Update Manager opened in Swedish, and dpkg --audit and apt-get check reported no package errors. These observations apply to that earlier revision. Xvfb does not verify physical-device behavior or hardware acceleration.

Localization

English is the source and default language. The app uses the desktop locale to select translations; Swedish strings live in po/sv.po. Add more languages through gettext catalogs and list their language codes in po/LINGUAS. Regenerate the template with xgettext and validate catalogs with msgfmt --check.

See po/README.md for instructions on updating Swedish translations and contributing another language.

Current limitations

Device troubleshooting guides are instructional. Optional network diagnostics run only after confirmation, use DNS for ubuntu.com and ping the local gateway, and do not upload a report. The app does not install packages or run privileged operations; system changes remain in Ubuntu's own tools. Settings panel names and the Additional Drivers launcher can differ across Ubuntu releases, so validate integrations on each supported release.

Releases

Tagged versions (v*) are built by GitHub Actions. Releases include a source archive, an installable .deb package and SHA-256 checksums. The workflow also publishes the Python wheel and source distribution to PyPI after the repository is registered as a Trusted Publisher.

Screenshots

The screenshots show the welcome page, matching printer troubleshooting steps, a Wi-Fi how-to guide, accessibility instructions and local network and hardware status.

License

Ubuntu Start is licensed under the GNU General Public License version 3. See LICENSE.