If you just upgraded to Debian 13 Trixie and tried running sudo apt install mysql-workbench, you already know the result: nothing. The package simply does not exist in Debian’s default repositories. That is one of the first friction points developers and sysadmins hit when setting up a database workflow on Debian 13, and this guide solves it completely.

By the end of this tutorial, you will know how to install MySQL Workbench on Debian 13 using two proven methods: the official MySQL APT repository and the Snap package manager. You will also set up a live MySQL 8.4 LTS server, secure it properly, create a dedicated database user, configure a working Workbench connection, and fix the five most common errors people run into on Trixie.

This guide is written from a sysadmin perspective. Every command comes with an explanation of what it does and why it matters. No guesswork. No skipped steps.

What Is MySQL Workbench and Why Does It Matter on Debian 13?

MySQL Workbench is the official, Oracle-maintained graphical interface for MySQL. It bundles four major tools into one application: a SQL query editor, a visual schema designer, a server administration panel, and a data migration wizard.

For developers who work with databases daily, Workbench removes the need to memorize complex GRANT, ALTER TABLE, or SHOW PROCESSLIST commands. You get a point-and-click interface backed by the same MySQL engine you would run in production.

Debian 13 Trixie, released in August 2025, is a strong server and desktop platform. However, it does not bundle MySQL Workbench in its base APT repositories. You need to add the official MySQL APT source manually. This is exactly what this guide walks you through.

Prerequisites

Before you start, make sure your environment meets these requirements:

• Operating System: Debian 13 Trixie (desktop or server with a desktop environment installed)
• User Privileges: A user account with sudo access
• RAM: Minimum 2 GB. MySQL Workbench loads schema metadata into memory during EER diagram rendering, and 1 GB VMs will struggle
• Display Environment: GNOME, KDE, or XFCE installed. Workbench is a GUI application and will not run on a pure headless server without an X11 forwarding setup
• Internet Access: Required to download packages from MySQL’s official servers
• Terminal: You will run all commands from a standard Bash terminal

If you are on a headless server and want to use Workbench on a local machine to connect remotely, jump directly to the SSH tunnel section later in this guide.

Choosing Your Installation Method

There are two reliable methods to install MySQL Workbench on Debian 13.

Pick Method 1 if you also plan to install mysql-server on the same machine. Pick Method 2 if you just need the GUI client quickly.

Step 1: Update Your Debian 13 System

Always start with a full system update. This is not optional.

sudo apt update && sudo apt upgrade -y

What this does: apt update refreshes your local package index so Debian knows about the latest versions across all configured repositories. apt upgrade then installs any available updates for existing packages.

Why it matters: MySQL Workbench links against system libraries like libssl, libgtk-3, and libmysqlclient. If those libraries are out of date, Workbench will either fail to install or crash at launch with a library mismatch error. Updating first prevents that entirely.

On a freshly provisioned Debian 13 VM, skipping this step caused a GTK version mismatch that made Workbench crash at the splash screen every time. One apt upgrade fixed it.

Step 2: Install Required Dependencies

These four packages are needed before you can add MySQL’s APT repository.

sudo apt install -y wget gnupg ca-certificates apt-transport-https

Here is what each one does and why you need it:

• wget: Downloads the MySQL APT configuration package from dev.mysql.com. Without it, you would need to download the file manually through a browser.
• gnupg: MySQL’s APT repository is GPG-signed. Without gnupg, APT cannot verify the package signatures and will refuse to install anything from that repository, throwing a NO_PUBKEY error.
• ca-certificates: Validates the SSL certificate chain from MySQL’s servers. Without this, wget aborts with a certificate error before the download even starts.
• apt-transport-https: Allows APT to fetch repository metadata over HTTPS instead of plain HTTP. This is a security baseline requirement when adding any third-party APT source.

These four packages are lightweight. They install in seconds and form the foundation for everything that follows.

Step 3: Download the MySQL APT Repository Configuration Package

Navigate to your /tmp directory first, then download the MySQL APT config package.

cd /tmp
wget https://dev.mysql.com/get/mysql-apt-config_0.8.36-1_all.deb

What this does: This downloads a small .deb configuration package directly from MySQL’s official servers. This is not Workbench itself. It is a setup tool that writes the MySQL repository URL and its GPG signing key into your system’s APT sources.

Why /tmp? The /tmp directory is cleaned automatically on reboot. Downloading installer files there keeps your home directory clean and avoids leftover artifacts after the setup is complete.

Debian 13 Trixie note: If the filename in this URL updates after publication, go to dev.mysql.com/downloads/repo/apt/ in a browser, grab the latest filename, and substitute it in the command above. The version number in the filename changes with each MySQL release.

Step 4: Install the APT Config Package and Refresh the Package Cache

Now install the config package using dpkg.

sudo dpkg -i /tmp/mysql-apt-config_0.8.36-1_all.deb

What happens next: A blue ncurses dialog screen opens in your terminal. This dialog writes the MySQL APT source file to /etc/apt/sources.list.d/mysql.list.

Inside the dialog, do the following:

1. Make sure “MySQL Server & Cluster” shows mysql-8.4 or the latest LTS version
2. Select “Ok” to confirm and exit the dialog

Important for Trixie users: The dialog may not list Debian 13 (Trixie) by name yet. If you see only Debian 12 (Bookworm) in the list, select Bookworm. MySQL’s Trixie packages are available at repo.mysql.com/apt/debian/dists/trixie/ and will resolve correctly once you run the next command.

After the dialog closes, refresh your package cache:

sudo apt update

Why this update is critical: The MySQL repository was just added to your sources, but your local APT cache has not indexed it yet. Without this update, apt still reports E: Unable to locate package mysql-workbench-community. The update command fixes that.

Step 5: Install MySQL Workbench on Debian 13 Using the APT Repository

Now install Workbench directly from the MySQL APT repository you just added.

sudo apt install -y mysql-workbench-community

What this does: APT resolves and installs the mysql-workbench-community package along with all its required dependencies, including Python bindings for Workbench’s scripting engine and the GTK3 UI libraries.

Why mysql-workbench-community and not mysql-workbench? Debian’s own repositories include a package called mysql-workbench that is often outdated and may not support the MySQL 8.4 authentication protocol. The -community suffix targets Oracle’s official, up-to-date build directly.

After the install finishes, verify it worked:

mysql-workbench --version

Expected output:

MySQL Workbench Community 8.0.xx  Revision xxxxx  Build xxxxx

If you see that output, Workbench is installed and ready to launch.

Alternative Method: Install MySQL Workbench via Snap

If you want a faster setup without touching APT sources, use Snap. This is the best option for desktop users who just need the GUI client without managing a full MySQL server on the same machine.

Step 5a: Install Snapd

Snap is not installed by default on Debian 13 minimal images.

sudo apt install -y snapd
sudo snap install core

Why snap install core first? The core Snap is the base runtime image that all other Snap applications depend on. Installing it upfront prevents dependency errors when you install mysql-workbench-community in the next step.

Step 5b: Install MySQL Workbench via Snap

sudo snap install mysql-workbench-community

Step 5c: Grant Required Permissions

This step is often skipped, which causes silent failures inside Workbench.

sudo snap connect mysql-workbench-community:password-manager-service
sudo snap connect mysql-workbench-community:ssh-keys

Why these interfaces matter:

• password-manager-service: Workbench stores connection passwords in your system keychain. Without this grant, the “Store in Keychain” button inside Workbench does nothing and your passwords never save.
• ssh-keys: Workbench reads ~/.ssh/ to populate SSH tunnel configuration. Without this grant, the SSH tunnel feature is completely blind to your existing key pairs.

Launch Workbench from Snap with:

snap run mysql-workbench-community

Step 6: Install and Secure MySQL Server 8.4 LTS

Workbench is a client GUI. It needs a database server to connect to. If you do not have MySQL server installed yet, do it now.

sudo apt install -y mysql-server
sudo systemctl enable --now mysql

Why systemctl enable --now? The enable flag registers MySQL to start automatically on every system reboot. The --now flag starts it immediately without requiring a separate systemctl start mysql command. Using just start without enable is a common beginner mistake: the service runs once, then disappears after the next reboot.

Verify the service is running:

sudo systemctl status mysql

Expected output:

● mysql.service - MySQL Community Server
   Loaded: loaded (/lib/systemd/system/mysql.service; enabled)
   Active: active (running) since ...

Run the Security Script

sudo mysql_secure_installation

This interactive script handles five important hardening tasks. Here is what each prompt does and why you should not skip it:

• VALIDATE PASSWORD component: Enforces password complexity for all MySQL accounts. Enable it in any environment that is not a purely local sandbox.
• Remove anonymous users: Default MySQL installs include anonymous accounts that allow any local system user to connect without credentials. Remove them.
• Disallow remote root login: MySQL root should never be reachable over the network. If your application layer has a vulnerability, an exposed root account makes the damage catastrophic.
• Remove test database: The default test database is world-readable and serves no production purpose. Keeping it is a compliance risk.
• Reload privilege tables: Applies all changes immediately without restarting the service.

Running this script takes two minutes and converts your MySQL install from a development default into a production-grade baseline.

Step 7: Create a Dedicated MySQL User for Workbench

Never connect Workbench as root. Create a dedicated user instead.

sudo mysql -u root -p

Once you are inside the MySQL prompt, run:

CREATE USER 'wbuser'@'localhost' IDENTIFIED BY 'StrongPass@2026!';
GRANT ALL PRIVILEGES ON *.* TO 'wbuser'@'localhost' WITH GRANT OPTION;
FLUSH PRIVILEGES;
EXIT;

Why not use root in Workbench? Connecting as root means every accidental click in the GUI runs with full, unrestricted server access. A dedicated user lets you scope permissions. In production, replace *.* with a specific database name like myapp_db.* to enforce least-privilege access.

Why FLUSH PRIVILEGES? This writes the in-memory grant table changes to disk immediately. Without it, the new user account may not be recognized until the MySQL service restarts.

Step 8: Launch MySQL Workbench and Configure Your First Connection

Launch Workbench from the application menu or run it from the terminal:

mysql-workbench

Setting Up a Local Connection

On the Workbench home screen, click the + icon next to “MySQL Connections” and fill in the following:

• Connection Name: Debian13-Local (or any descriptive name)
• Connection Method: Standard (TCP/IP)
• Hostname: 127.0.0.1
• Port: 3306
• Username: wbuser

Why use 127.0.0.1 instead of localhost? Using localhost can trigger Unix socket resolution on some Debian configurations, which fails if MySQL’s socket path is non-standard. The IP address 127.0.0.1 forces a TCP/IP connection every time, which is more predictable.

Click Store in Keychain, enter your password, then click Test Connection. A green success dialog confirms everything is working. Click OK to save the connection.

Configure a Remote MySQL Connection via SSH Tunnel

If your MySQL server runs on a remote Debian 13 machine, do not open port 3306 to the internet. Use an SSH tunnel instead.

In the connection dialog, set:

• Connection Method: Standard TCP/IP over SSH
• SSH Hostname: your.server.ip:22
• SSH Username: your Linux username
• SSH Key File: ~/.ssh/id_rsa
• MySQL Hostname: 127.0.0.1
• MySQL Port: 3306

Why SSH tunnel instead of opening port 3306 in your firewall? SSH port 22 is already open for server administration. Tunneling MySQL through it requires zero additional firewall rules, and every byte of traffic is encrypted in transit. It is the correct approach for any internet-facing server.

Troubleshooting Common Errors on Debian 13

Error 1: E: Unable to locate package mysql-workbench-community

Cause: apt update was not run after adding the MySQL APT repository.

Fix:

sudo apt update
sudo apt install -y mysql-workbench-community

Error 2: NO_PUBKEY During apt update

Cause: The GPG key for MySQL’s APT repository was not imported.

Fix:

sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys B7B3B788A8D3785C
sudo apt update

Error 3: MySQL Workbench Crashes at Launch (Segmentation Fault)

Cause: Missing libGL or libgtk-3 libraries on minimal Debian 13 installs without a full desktop environment.

Fix:

sudo apt install -y libgl1-mesa-glx libgtk-3-0

Relaunch Workbench after the install.

Error 4: Authentication plugin 'caching_sha2_password' cannot be loaded

Cause: You are using an older Workbench build (pre-8.0.4) that does not support MySQL 8.4’s default authentication plugin.

Fix: Update Workbench first:

sudo apt upgrade mysql-workbench-community

If the error persists, you can temporarily change the user’s auth method inside MySQL:

ALTER USER 'wbuser'@'localhost' IDENTIFIED WITH mysql_native_password BY 'YourPassword';
FLUSH PRIVILEGES;

Plan to upgrade Workbench as soon as possible. Running mysql_native_password long-term is not recommended for production environments.

Error 5: Snap Workbench Cannot Access SSH Keys

Cause: The ssh-keys Snap interface was never connected after installation.

Fix:

sudo snap connect mysql-workbench-community:ssh-keys

Then restart Workbench. The SSH tunnel file selector should now show your key files.

Verify Your Full Installation

Run these five quick checks to confirm everything is working end to end:

1. Confirm MySQL server is installed:

   mysql --version

   Expected: mysql Ver 8.4.x Distrib 8.4.x, for Linux (x86_64)

2. Confirm the MySQL service is active:

   sudo systemctl status mysql

   Expected: Active: active (running)

3. Confirm Workbench binary is accessible:

   mysql-workbench --version

   Expected: MySQL Workbench Community 8.x.xx

4. Test the connection inside Workbench: Click your saved connection, then click Test Connection. Look for the green success dialog.
5. Run a live query: Open the SQL Editor inside Workbench and run:

   SELECT VERSION();

   Expected output: 8.4.x (your installed MySQL version)

If all five checks pass, your setup is complete and production-ready.