TK
Docs
Top Tags

Using gnome-tweaks to customize Ubuntu

Use gnome-tweaks to customize your Ubuntu desktop environment

ubuntugnometweakscustomizationgtkthemesicons

Introduction to GNOME Customization

GNOME Shell is the default desktop environment for Ubuntu (since 17.10) and provides a modern, clean interface. However, its customization options are limited out of the box. This guide covers the essential tools and techniques for customizing GNOME's appearance, including themes, icons, extensions, and system-wide visual elements.

Understanding GNOME Architecture

GNOME uses several key technologies for theming:

  • GTK (GIMP Toolkit): Framework for creating graphical user interfaces, handles application window theming
  • GNOME Shell Theme: Controls the appearance of the top bar, activities overview, and system elements
  • Icon Theme: Defines system-wide icon appearance across applications and file managers
  • Cursor Theme: Customizes mouse pointer appearance

Installing Essential Tools

GNOME Shell Extension Manager

The Extension Manager is the modern, user-friendly tool for managing GNOME Shell extensions. It replaces the older browser-based extension management and provides a native application experience.

Bash
1sudo apt install gnome-shell-extension-manager

Technical Note: Extension Manager uses the GNOME Extensions API to safely install, enable, and disable extensions. It automatically handles compatibility checking with your GNOME Shell version.

GNOME Shell Extensions Package

This package provides the base infrastructure for running GNOME Shell extensions. Extensions are JavaScript-based plugins that modify or extend GNOME Shell functionality.

bash
1sudo apt install gnome-shell-extensions

What this package includes:

  • Core extension system libraries
  • Several pre-installed extensions (window list, places menu, applications menu)
  • DBus service for extension management
  • Schema files for extension settings

Official Resources

bash
1sudo apt install gnome-shell-extensions

Extension Repositories:

https://gitlab.gnome.org/GNOME/gnome-shell-extensions https://extensions.gnome.org/extension/19/user-themes/

Important Extension: User Themes - The User Themes extension is essential for applying custom GNOME Shell themes. Without it, you can only customize GTK application themes, not the shell itself (top bar, overview, etc.).

Theming System Overview

Theme Installation Locations

GNOME looks for themes in two primary directories:

  • System-wide: /usr/share/themes/ - Available to all users, requires sudo
  • User-specific: ~/.themes/ or ~/.local/share/themes/ - Per-user themes

Icons follow a similar pattern:

  • System-wide: /usr/share/icons/
  • User-specific: ~/.icons/ or ~/.local/share/icons/

Theme Structure

A complete GTK theme typically contains:

ThemeName/ ├── gtk-2.0/ # GTK2 applications ├── gtk-3.0/ # GTK3 applications (most current apps) ├── gtk-4.0/ # GTK4 applications (newer apps) ├── gnome-shell/ # GNOME Shell theme ├── metacity-1/ # Window manager decorations └── index.theme # Theme metadata

Install WhiteSur Theme

WhiteSur is a macOS Big Sur-like theme for GNOME/GTK desktop environments. It provides a polished, modern look inspired by Apple's design language.

Repository: https://github.com/vinceliuice/WhiteSur-gtk-theme

Features:

  • Full GTK3/GTK4 theme support
  • GNOME Shell theme variants
  • Multiple color schemes (Light, Dark)
  • Firefox, Flatpak, and Snap application support
  • Customizable panel opacity and height

Clone the Repository

bash
1git clone https://github.com/vinceliuice/WhiteSur-gtk-theme

Installation Options

After cloning, navigate to the directory and run the install script:

bash
1cd WhiteSur-gtk-theme
2./install.sh

Advanced Installation Examples:

bash
1# Install with specific color variants
2./install.sh -c Light   # Light variant only
3./install.sh -c Dark    # Dark variant only
4

5# Install with custom panel opacity
6./install.sh -o solid   # Solid panel
7./install.sh -o normal  # Normal transparency
8

9# Install with alt variant (alternative style)
10./install.sh -a alt
11

12# Install to system directory (all users)
13sudo ./install.sh -d /usr/share/themes/
14

15# Combine options
16./install.sh -c Dark -o solid -a alt

Install script parameters:

  • -d [DIR]: Destination directory (default: ~/.themes)
  • -n [NAME]: Theme name (default: WhiteSur)
  • -o [OPACITY]: Panel opacity - solid/normal (default: normal)
  • -c [COLOR]: Color variant - Light/Dark (default: All)
  • -a [ALT]: Alternative style variant
  • -t [THEME]: Theme color - default/blue/purple/pink/red/orange/yellow/green/grey
  • -p [PANEL]: Panel size - default/smaller/bigger
  • -s [SIZE]: Sidebar size - default/220/240/260/280
  • -i [ICON]: Icon variant - default/gnome/ubuntu/arch/manjaro/fedora/debian
  • -h: Display help
bash
1git clone https://github.com/vinceliuice/WhiteSur-gtk-theme

Applying the Theme

After installation, activate the theme using GNOME Tweaks or command line:

Using GNOME Tweaks:

  1. Open GNOME Tweaks (gnome-tweaks)
  2. Navigate to "Appearance"
  3. Select WhiteSur from "Applications" dropdown
  4. Select WhiteSur from "Shell" dropdown (requires User Themes extension)

Using Command Line (gsettings):

bash
1# Set GTK theme
2gsettings set org.gnome.desktop.interface gtk-theme 'WhiteSur-Dark'
3

4# Set Shell theme (requires User Themes extension)
5gsettings set org.gnome.shell.extensions.user-theme name 'WhiteSur-Dark'
6

7# Set icon theme (after installing WhiteSur icons)
8gsettings set org.gnome.desktop.interface icon-theme 'WhiteSur-dark'
9

10# View current theme settings
11gsettings get org.gnome.desktop.interface gtk-theme

Icons

WhiteSur Icon Theme - Complements the WhiteSur GTK theme with macOS-style icons.

Repository: https://github.com/vinceliuice/WhiteSur-icon-theme

Installation:

bash
1# Clone the repository
2git clone https://github.com/vinceliuice/WhiteSur-icon-theme.git
3cd WhiteSur-icon-theme
4

5# Install for current user
6./install.sh
7

8# Install specific variants
9./install.sh -a    # Install all variants
10./install.sh -b    # Install bold variant
11./install.sh -d /usr/share/icons/  # System-wide installation

Icon Theme Structure: Icon themes contain different sizes and contexts:

IconTheme/ ├── 16x16/ # Small icons ├── 22x22/ ├── 24x24/ ├── 32x32/ ├── 48x48/ ├── scalable/ # SVG icons ├── symbolic/ # Monochrome symbolic icons └── index.theme # Icon theme metadata

Verify Installation:

bash
1# List installed icon themes
2ls ~/.local/share/icons/
3ls /usr/share/icons/
4

5# Apply icon theme
6gsettings set org.gnome.desktop.interface icon-theme 'WhiteSur-dark'

Cursor

Bibata Modern Ice - A modern, smooth cursor theme with excellent visibility.

Download: https://www.gnome-look.org/p/1197198

Manual Installation:

bash
1# Create cursors directory if it doesn't exist
2mkdir -p ~/.local/share/icons
3

4# Extract downloaded cursor theme
5cd ~/.local/share/icons
6tar -xvf ~/Downloads/Bibata-Modern-Ice.tar.gz
7

8# Verify installation
9ls ~/.local/share/icons/Bibata-Modern-Ice/
10

11# Apply cursor theme
12gsettings set org.gnome.desktop.interface cursor-theme 'Bibata-Modern-Ice'

Alternative: Install via Package Manager (if available):

bash
1# Some distributions include Bibata in repos
2sudo apt search bibata

Cursor Theme Technical Details:

  • Format: X11 cursor format (Xcursor)
  • Sizes: Multiple resolutions (24px, 32px, 48px, etc.) for HiDPI support
  • Hot spot: Defined click point for each cursor state
  • Animated cursors: Frame-based animation support

Creating Cursor Symlinks (for applications that need absolute paths):

bash
1# Link to system directory for compatibility
2sudo ln -s ~/.local/share/icons/Bibata-Modern-Ice /usr/share/icons/

Complete Setup for Ubuntu with GNOME 49+

For modern GNOME versions (49 and later), this comprehensive package installation includes all necessary tools for customization.

bash
1sudo apt install gnome-shell-extensions gnome-tweaks gnome-shell-extension-manager chrome-gnome-shell git unzip chrome-gnome-shell

Package Breakdown:

PackagePurposeKey Features
gnome-shell-extensionsCore extensions bundleBase extensions, system integration
gnome-tweaksGUI customization toolAdvanced settings, theme management
gnome-shell-extension-managerModern extension managerBrowse, install, manage extensions
chrome-gnome-shellBrowser integrationInstall extensions from extensions.gnome.org
gitVersion controlClone theme repositories
unzipArchive extractionExtract downloaded themes/icons

Post-Installation Steps:

  1. Enable Browser Integration:

  2. Restart GNOME Shell:

    bash
    1# On X11
    2killall -3 gnome-shell
    3

    4# On Wayland (logout and login required)
    5# Or press Alt+F2, type 'r', and press Enter

  3. Verify Installation:

    bash
    1# Check GNOME Shell version
    2gnome-shell --version
    3

    4# List installed extensions
    5gnome-extensions list
    6

    7# Check extension status
    8gnome-extensions info [extension-name]

Advanced Customization Techniques

Using GNOME Tweaks

GNOME Tweaks provides access to advanced settings:

bash
1# Launch GNOME Tweaks
2gnome-tweaks

Key Customization Areas:

  • Appearance: Themes, background, icons, cursor
  • Extensions: Enable/disable extensions
  • Fonts: System fonts, scaling, hinting
  • Keyboard & Mouse: Additional input settings
  • Power: Laptop lid settings, power button behavior
  • Startup Applications: Auto-start programs
  • Top Bar: Clock format, calendar, battery percentage
  • Window Titlebars: Titlebar buttons, actions
  • Windows: Window focus, edge tiling, center new windows

Managing Extensions via Command Line

bash
1# List all extensions
2gnome-extensions list
3

4# Enable an extension
5gnome-extensions enable [email protected]
6

7# Disable an extension
8gnome-extensions disable [email protected]
9

10# Show extension info
11gnome-extensions info [email protected]
12

13# Uninstall an extension
14gnome-extensions uninstall [email protected]
15

16# List enabled extensions only
17gnome-extensions list --enabled
18

19# Create new extension (for developers)
20gnome-extensions create --name="My Extension" --uuid="[email protected]"

GNOME Shell CSS Customization

For advanced users, GNOME Shell appearance can be customized via CSS:

Location: ~/.local/share/gnome-shell/extensions/[extension-name]/stylesheet.css

Example Custom CSS Tweaks:

css
1/* Customize panel (top bar) */
2#panel {
3    background-color: rgba(0, 0, 0, 0.8);
4    height: 32px;
5}
6

7/* Customize panel text */
8#panel .panel-button {
9    color: #ffffff;
10    font-weight: bold;
11}
12

13/* Customize workspace switcher */
14.workspace-thumbnail {
15    border: 2px solid #3584e4;
16}
17

18/* Overview background */
19.workspace-background {
20    background-color: #2e3436;
21}

DConf Editor for Deep System Settings

For even deeper customization, use DConf Editor:

bash
1# Install dconf-editor
2sudo apt install dconf-editor
3

4# Launch
5dconf-editor
6

7# Or use gsettings from command line
8# List all schemas
9gsettings list-schemas | grep gnome
10

11# Get all keys in a schema
12gsettings list-keys org.gnome.desktop.interface
13

14# Set a value
15gsettings set org.gnome.desktop.interface enable-animations false
16

17# Reset to default
18gsettings reset org.gnome.desktop.interface enable-animations

Useful GSettings Paths:

  • org.gnome.desktop.interface - Interface settings (theme, icons, fonts)
  • org.gnome.desktop.wm.preferences - Window manager preferences
  • org.gnome.shell - Shell settings
  • org.gnome.shell.extensions.* - Extension-specific settings
  • org.gnome.desktop.peripherals - Input device settings

Troubleshooting

Extension Not Working After GNOME Update

bash
1# Disable and re-enable extension
2gnome-extensions disable [email protected]
3gnome-extensions enable [email protected]
4

5# Check extension compatibility
6gnome-extensions info [email protected] | grep -i version
7

8# View extension errors
9journalctl -f -o cat /usr/bin/gnome-shell

Theme Not Applying

bash
1# Check theme directory permissions
2ls -la ~/.themes/
3ls -la ~/.local/share/themes/
4

5# Ensure User Themes extension is enabled
6gnome-extensions enable [email protected]
7

8# Reset theme settings
9gsettings reset org.gnome.desktop.interface gtk-theme
10gsettings reset org.gnome.shell.extensions.user-theme name

Clear Extension Cache

bash
1# Remove extension cache
2rm -rf ~/.cache/gnome-shell/
3

4# Restart GNOME Shell (X11)
5killall -3 gnome-shell

Additional Resources

Popular GNOME Extensions:

  • Dash to Dock: macOS-like dock
  • AppIndicator Support: Tray icons support
  • Blur My Shell: Blur effects for shell elements
  • Clipboard Indicator: Clipboard manager
  • Desktop Icons NG: Icons on desktop
  • ArcMenu: Alternative application menu
  • Vitals: System monitoring in top bar
  • GSConnect: KDE Connect integration

Theme Resources:

Command Reference:

bash
1# System information
2gnome-shell --version
3echo $XDG_CURRENT_DESKTOP
4echo $XDG_SESSION_TYPE  # wayland or x11
5

6# Theme directories
7echo $XDG_DATA_HOME  # ~/.local/share
8echo $XDG_DATA_DIRS  # /usr/local/share:/usr/share
9

10# Reload GNOME settings
11dconf update
12

13# Export current settings
14dconf dump / > gnome-settings-backup.txt
15

16# Import settings
17dconf load / < gnome-settings-backup.txt