Portname: Rename Audio Ports on Linux

Ever wished you could change "Line Out" to "JBL Headset" or "Headphones" to "Pebble Speakers" in your Sound Settings? Now you can.

Portname lets you rename the audio input/output ports that appear in your system's Sound Settings panel. Works with PipeWire and ALSA on any Linux distribution, for both built-in sound cards and USB audio devices.

Before & After

Before:                              After:
  Line Out                             JBL Headset
  Starship/Matisse HD Audio            Starship/Matisse HD Audio

  Headphones                           Pebble Speakers
  Starship/Matisse HD Audio            Starship/Matisse HD Audio

Install

pip install portname

To update to the latest version:

pip install --upgrade portname

Alternative, install from source:

git clone https://github.com/offbyonebit/portname.git
cd portname
chmod +x install.sh
./install.sh

To update a source installation, run these commands from its checkout. The installer must be run again because it copies the code into /usr/lib/portname:

git pull --ff-only origin master
./install.sh
sudo portname repair

Usage

GUI (recommended for beginners)

Just run portname or find Portname in your application menu. Click Rename next to any audio port, type a new name, and enter your password when prompted.

Command Line

# List all audio devices and ports
portname list

# Rename a port (requires sudo)
sudo portname rename analog-output-lineout "JBL Headset"
sudo portname rename analog-output-headphones "Pebble Speakers"
sudo portname rename analog-input-rear-mic "JBL Headset Mic"

# When several devices share a route, select the device shown by 'portname list'
sudo portname rename analog-stereo "USB Headset" --device alsa_card.usb-Generic_USB_Audio_1234-00

# Revert a single port
sudo portname revert analog-output-lineout

# Revert all renamed ports
sudo portname revert --all

# Check for renames clobbered by a package upgrade and re-apply them (Arch/Fedora)
sudo portname check

# Recover missing ports left by older versions (also available in the GUI)
sudo portname repair

# Toggle Auto-Mute Mode (fixes issue where front jack silences rear jacks)
portname auto-mute off
portname auto-mute on
portname auto-mute status

How It Works

Portname picks the method for you based on the device.

Built-in (PCI/HDA) sound cards

Audio port names on Linux come from ALSA card profile path files in /usr/share/alsa-card-profile/mixer/paths/. Portname:

1. Backs up the original file to <name>.conf.orig
2. Writes a modified copy with your custom name
3. Restarts PipeWire so the change appears immediately

Your custom names survive reboots. On Debian/Ubuntu the backup is registered with dpkg-divert, which also tells the package manager to skip the file on upgrades. On other distros (Arch, Fedora, etc.) the backup/restore logic is identical but there is no package-manager hook. An upgrade of alsa-card-profile can silently overwrite the modified file. Run sudo portname check after such an upgrade to detect and automatically re-apply any clobbered names. AUR/Copr package descriptions should note this and suggest adding a post-upgrade hook that calls portname check.

Recovering missing ports on Linux Mint / Ubuntu

Older versions could leave the original profile in a .conf.distrib backup while looking for .conf.orig. After updating, click Repair Missing Ports in the GUI or run sudo portname repair. This restores missing profiles even when no custom name was saved, and reapplies saved names where available. Existing .distrib diversions are supported without manual removal. Repair keeps the original backup and reports any files it cannot recover. It also restores overwritten USB rename rules. Revert all removes both the rules and saved USB names, so repair will not bring reverted names back.

USB audio devices

USB devices (headsets, DACs, webcams) have no ALSA profile path to edit, so portname rename writes a WirePlumber rule instead and restarts PipeWire. The command is the same as for built-in cards. Portname detects your WirePlumber version and writes the matching format:

• WirePlumber 0.4 (Ubuntu 24.04, Linux Mint 22): a Lua rule at /etc/wireplumber/main.lua.d/90-portname-<node>.lua
• WirePlumber 0.5+: a config rule at /etc/wireplumber/wireplumber.conf.d/90-portname-<node>.conf

portname revert deletes the rule, and ./install.sh --uninstall removes any left over.

Compatibility

Distro	Status
Linux Mint 22	Fully tested
Ubuntu 22.10+	Fully tested
Arch Linux	Core features tested via CI, real-machine audio feedback not yet verified
Fedora	Core features tested via CI, real-machine audio feedback not yet verified
Other PipeWire distros	Should work, but untested

Arch / Fedora users: portname works on your distro, but hasn't been tested by a real person on real hardware yet. If something doesn't behave as expected, names not showing up in Sound Settings, the audio system not restarting, anything, please open an issue and describe what happened. That feedback is how we close the gap.

Does not work on distros still using PulseAudio without PipeWire.

Requirements

• Linux with PipeWire (standard on most distros from 2022 onward)
• Python 3.8+
• GTK3 via PyGObject (pre-installed on most desktop Linux distros)

Uninstall

cd portname
./install.sh --uninstall

This reverts all renamed ports to their original names and removes portname.

Support

This project is free and I don't ask for anything. If it's useful to you, a star on the repo is appreciated, and if you want to follow along with other things I'm building, you can find them under @offbyonebit.

If you'd like to support development, you can sponsor me on GitHub.

License

MIT