Ubuntu Hello provides Windows Hello™ style authentication for Linux. Use your built-in IR emitters and camera in combination with facial recognition to prove who you are.

Using the central authentication system (PAM), this works everywhere you would otherwise need your password: Login, lock screen, sudo, su, etc.

Supported releases

Ubuntu 22.04 LTS (jammy), 24.04 LTS (noble) and 26.04 LTS (resolute), and derivatives built on them (e.g. Linux Mint 21 and 22). On 22.04 the dropdowns in Settings have no type-ahead search: its PyGObject (3.42) cannot pass GTK the search expression. Everything else works the same.

Supported desktops

Face authentication via PAM (common-auth) is desktop-agnostic and works with GDM, SDDM, LightDM, and similar display managers.

Desktop	Theme follow	Wallet auto-unlock (PAM_AUTHTOK)
GNOME / Ubuntu	Yes	GNOME Keyring (pam_gnome_keyring)
KDE Plasma	Yes	KWallet (pam_kwallet5, package libpam-kwallet5)
XFCE	Yes	GNOME Keyring when present
Cinnamon	Yes	GNOME Keyring when present
MATE	Yes	GNOME Keyring when present
Budgie	Yes	GNOME Keyring when present
LXQt	Yes (best-effort)	GNOME Keyring when present

Auto-unlock after face login reuses the same sealed password blob and sets PAM_AUTHTOK for whichever wallet PAM module is in the stack. There is no separate KWallet credential format.

⚡ Quick Install

Open a terminal and run:

curl -fsSL https://raw.githubusercontent.com/ventura8/ubuntu-hello/master/install.sh | sudo bash

That's it! The installer will automatically:

• ✅ Install all required system dependencies
• ✅ Build and install Ubuntu Hello from source
• ✅ Download face recognition AI models (~100 MB)
• ✅ Configure PAM for system-wide facial authentication
• ✅ Set up Polkit for App Center face auth
• ✅ Open the configuration GUI when finished

After installation, the setup wizard should open automatically (approve the polkit prompt if asked). If it does not, run ubuntu-hello-gtk --force-onboarding.

Uninstall

To completely remove Ubuntu Hello from your system:

curl -fsSL https://raw.githubusercontent.com/ventura8/ubuntu-hello/master/uninstall.sh | sudo bash

Or if you have the repo cloned:

sudo bash uninstall.sh

Installation (alternative methods)

Ubuntu or Linux Mint (PPA)

sudo add-apt-repository ppa:ventura8/ubuntu-hello
sudo apt update
sudo apt install ubuntu-hello

The PPA publishes builds for Ubuntu 22.04 (jammy), 24.04 (noble) and 26.04 (resolute).

Debian

Download the .deb file from the Releases page and install with gdebi.

Building from source manually

Click to expand manual build instructions

Dependencies

• Python 3.6 or higher (with pip, setuptools, wheel)
• meson ≥ 0.61
• ninja
• dlib (compiled via pip)
• INIReader (pulled from git automatically if not found)
• libevdev

Install dependencies on Ubuntu/Debian:

sudo apt-get update && sudo apt-get install -y \
  python3 python3-pip python3-dev python3-setuptools python3-wheel \
  python3-numpy python3-opencv python3-gi python3-gi-cairo \
  python3-babel gir1.2-gtk-4.0 \
  cmake make build-essential g++ \
  libpam0g-dev libinih-dev libevdev-dev libopencv-dev \
  libboost-all-dev pkg-config \
  meson ninja-build git curl wget bzip2 \
  v4l-utils libopenblas-dev liblapack-dev

Install dlib:

pip3 install dlib --break-system-packages

Build & Install

meson setup builddir -Dprefix=/usr -Dsysconfdir=/etc -Dlibdir=lib \
  -Dinstall_pam_config=true -Dwith_polkit=true -Dfetch_dlib_data=true \
  -Dinih:with_INIReader=true
meson compile -C builddir
sudo meson install -C builddir

Setup

After installation, Ubuntu Hello needs to learn what you look like so it can recognise you later. The installer launches the setup wizard automatically only when no face models are enrolled yet (Wayland/X11 session-aware). If it does not appear, run sudo cat /run/ubuntu-hello/postinstall.log or ubuntu-hello-gtk --force-onboarding.

If nothing went wrong we should be able to run sudo by just showing your face. Open a new terminal and run sudo -i to see it in action. Please check this wiki page if you're experiencing problems or search for similar issues.

If you're curious you can run sudo ubuntu-hello config to open the central config file and see the options Ubuntu Hello has to offer. On most systems this will open the nano editor, where you have to press ctrl+x to save your changes.

CLI

The installer adds a ubuntu-hello command to manage face models for the current user. Use ubuntu-hello --help or man ubuntu-hello to list the available options.

Usage:

ubuntu-hello [-U user] [-y] command [argument]

Command	Description
add	Add a new face model for a user
clear	Remove all face models for a user
config	Open the config file in your default editor
disable	Disable or enable ubuntu-hello
keyring	Manage automatic login keyring / KWallet unlocking (enable / disable / restore [--all])
list	List all saved face models for a user
remove	Remove a specific model for a user
set	Change a configuration option directly
snapshot	Take a snapshot of your camera input
test	Test the camera and recognition methods
version	Print the current version number

Contributing

The easiest ways to contribute to Ubuntu Hello is by starring the repository and opening GitHub issues for features you'd like to see.

Code contributions are also very welcome. If you want to port Ubuntu Hello to another distro, feel free to open an issue for that too.

Troubleshooting

Any Python errors get logged directly into the console and should indicate what went wrong. If authentication still fails but no errors are printed, you could take a look at the last lines in /var/log/auth.log to see if anything has been reported there.

Face login works but the keyring keeps asking for a password. Log in once with your typed password. If the keyring rejects that too (journalctl -b | grep gkr-pam shows the password for the login keyring was invalid), the keyring file itself is damaged or its password no longer matches your login password. Face login is not the cause. Run sudo ubuntu-hello keyring repair (or Repair Keyring in the Keyring tab, which appears when this is detected), then log out and back in. The old keyring is kept as login.keyring.broken-<date>, and passwords saved in it need to be entered again.

Please first check the wiki on common issues and if you encounter an error that hasn't been reported yet, don't be afraid to open a new issue.

🤖 AI Assistance

If you are developing or modifying this codebase using an AI coding assistant, start from the canonical rules and skills:

• AGENTS.md — Workspace guidelines, architecture summary, coding standards, CI/Docker matrix rules (shared across tools).
• docs/INSTRUCTIONS.md — Build, install, extend, and debug.
• docs/architecture/README.md — Component deep dive.
• .agents/skills/ — Focused runbooks (SKILL.md per workflow).

Thin tool entrypoints (point at AGENTS.md, do not fork rules): CLAUDE.md, GEMINI.md, .github/copilot-instructions.md. Legacy stubs: agent.md, skills.md.

A note on security

This package is in no way as secure as a password and will never be. Although it's harder to fool than normal face recognition, a person who looks similar to you, or a well-printed photo of you could be enough to do it. Ubuntu Hello is a more quick and convenient way of logging in, not a more secure one.

To minimize the chance of this program being compromised, it's recommended to leave Ubuntu Hello in /lib/security and to keep it read-only.

DO NOT USE UBUNTU_HELLO AS THE SOLE AUTHENTICATION METHOD FOR YOUR SYSTEM.