MKV Episode Matcher
Automatically match and rename your MKV TV episodes using advanced speech recognition and subtitle matching.
🚀 Quick Start
Follow these steps to get up and running in minutes.
1. Prerequisites
Before you start, ensure you have the following:
- FFmpeg: Installed and added to your system PATH.
- API Keys:
- OpenSubtitles.com account (for downloading subtitles).
- TMDb API Key (for fetching episode titles).
- Directory Structure: Your files must be organized by Show/Season. See Directory Structure below.
2. Install & Launch
The easiest way to run MKV Episode Matcher is using the standalone Windows executable.
- Download the latest
mkv-match.exefrom GitHub Releases. - Double-click
mkv-match.exeto launch. - The Web UI will automatically open in your default browser at
http://localhost:8001.
3. Setup
- In the Web UI, go to the Settings tab.
- Enter your OpenSubtitles credentials and TMDb API Key.
- Click Save.
4. Make Your First Match
- Go to the Dashboard.
- Use the file browser to navigate to a folder containing your TV show episodes.
- Click "Scan This Folder".
- The system will analyze your files and propose matches. You can review them before confirming the rename.
✨ Key Features
- Modern Web Interface: Easy-to-use Dashboard with dark mode.
- Advanced Speech Recognition: Identifies episodes by listening to the audio.
- Smart Subtitles: Automatically downloads subtitles from OpenSubtitles.
- Safe: Review matches before any files are renamed.
🛠️ Advanced Installation & Usage
For developers, Linux/macOS users, or those preferring the command line.
Option A: Install via pip (Cross-platform)
# Basic install
pip install mkv-episode-matcher[cpu]
# With CUDA support (NVIDIA GPU required)
pip install mkv-episode-matcher[cu128]
Option B: Run from Source (Development)
We recommend using uv for dependency management.
git clone https://github.com/Jsakkos/mkv-episode-matcher.git
cd mkv-episode-matcher
# Install dependencies
uv sync --extra cpu
# Launch Server
uv run mkv-match serve
CLI Mode
You can also use the Command Line Interface (CLI) for automation. Make sure to run the command from the root directory of the repository or your home directory, not the show directory.
# Match a folder
mkv-match match "C:\Path\To\Show"
# Match with subtitle download
mkv-match match "C:\Path\To\Show" --get-subs
Building the Executable
To build the .exe yourself:
uv sync --extra cpu
uv run pyinstaller mkv_match.spec
Reference Subtitle Structure
If you have your own subtitles or don't use the auto-download feature, ensure your files are named correctly so the system can find them.
Cache Directory: C:\Users\{username}\.mkv-episode-matcher\cache\data\
Naming Format:
{show_name} - S{season:02d}E{episode:02d}.srt
Example:
Show Name/
├── Show Name - S01E01.srt
├── Show Name - S01E02.srt
Contributing
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
License
Distributed under the MIT License. See LICENSE for more information.
Documentation
Full documentation is available at https://jsakkos.github.io/mkv-episode-matcher/
1 maintainer
Metadata
1 maintainer
Release files for mkv-episode-matcher 1.3.6
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| mkv_episode_matcher-1.3.6.tar.gz | 1.2 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| mkv_episode_matcher-1.3.6-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 1.4 MB
Release files / mkv_episode_matcher-1.3.6.tar.gz
| Download URL | mkv_episode_matcher-1.3.6.tar.gz |
|---|---|
| Size | 1.2 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
a369eb54b5e0f282d457b0202f129d59b4ea09a36fe2e9d02b8fedf42ac426ad
|
|
BLAKE2b-256 checksum How to use checksums |
ed218c1d1650ff5cfaeaa1a86f77c76bd958838d65a9e39dffd466ae4c278e43
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Apr 18, 2026.
Transparency logRelease files / mkv_episode_matcher-1.3.6-py3-none-any.whl
| Download URL | mkv_episode_matcher-1.3.6-py3-none-any.whl |
|---|---|
| Size | 197.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
5c181c77de29eddf616996d0eb024702d08def5f182ee6bafb957e036f4c0f3c
|
|
BLAKE2b-256 checksum How to use checksums |
131ce08486636adf8ad34b69a92a414052cf9fb1e3793824be7ab8ef65dccb24
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Apr 18, 2026.
Transparency log
