Skip to main content
This guide will walk you through installing TagQt and its dependencies on your system.

​
System requirements

Before installing TagQt, ensure your system meets the following requirements:

​
Required

  • Python 3.10 or higher - TagQt requires modern Python features
  • pip - Python package installer

​
Optional dependencies

FFmpeg is required if you want to re-encode FLAC files. Install it using your system package manager:
Ubuntu/Debian
sudo apt install ffmpeg
Fedora
sudo dnf install ffmpeg
Arch Linux
sudo pacman -S ffmpeg
Without FFmpeg, the re-encode FLAC feature will not be available.

​
Installation steps

1

Clone the repository

First, clone the TagQt repository from GitHub:
git clone https://github.com/selr1/tagqt.git
cd tagqt
2

Create a virtual environment (recommended)

Creating a virtual environment keeps TagQt’s dependencies isolated from your system Python:
python -m venv venv
Activate the virtual environment:
Linux/macOS
source venv/bin/activate
Windows
venv\Scripts\activate
While optional, using a virtual environment is strongly recommended to avoid package conflicts.
3

Install Python dependencies

Install all required Python packages using pip:
pip install -r requirements.txt
This will install the following packages:
  • PySide6 - Qt bindings for Python
  • mutagen - Audio metadata library
  • Pillow - Image processing for cover art
  • requests - HTTP library for online lookups
  • koroman - Korean romanization (optional)
  • musicbrainzngs - MusicBrainz API client
4

Verify installation

Test that TagQt launches successfully:
python main.py
The TagQt window should open. If you see the main interface with “TagQt” in the header, you’re all set!

​
Troubleshooting

​
Python version issues

If you encounter errors about Python version: 
python --version
Ensure the output shows Python 3.10 or higher. On some systems, you may need to use python3 instead of python: 
python3 --version
python3 -m venv venv
python3 main.py

​
Missing dependencies

If you see import errors when running TagQt, ensure all dependencies were installed: 
pip list
Verify that PySide6, mutagen, Pillow, requests, and musicbrainzngs appear in the list. If any are missing, reinstall: 
pip install -r requirements.txt

​
PySide6 installation fails

PySide6 requires Qt libraries. On Linux, you may need to install additional system packages:
Ubuntu/Debian
sudo apt install python3-pyqt6 libqt6widgets6
Fedora
sudo dnf install python3-qt6

​
Permission errors

If you encounter permission errors during installation:
Never use sudo pip install as it can break your system Python. Always use a virtual environment instead.
Ensure you’re in a virtual environment (see Step 2 above) and retry the installation.

​
FFmpeg not found

If the re-encode FLAC feature shows a “Missing Dependency” error, verify FFmpeg is installed: 
ffmpeg -version
If not found, install it using your package manager (see Optional dependencies above).

​
Launching TagQt

Once installed, you can launch TagQt anytime by:
  1. Navigating to the TagQt directory
  2. Activating your virtual environment (if used)
  3. Running python main.py
cd /path/to/tagqt
source venv/bin/activate  # if using virtual environment
python main.py
Consider creating a shell script or desktop shortcut for quick access to TagQt.

​
Next steps

Now that TagQt is installed, learn how to use it:

Quick start guide

Follow our step-by-step tutorial to edit your first audio files

Build docs developers (and LLMs) love

Get started for freeTalk to us