YTMusicFS - YouTube Music FUSE Filesystem

YTMusicFS mounts your YouTube Music library as a standard filesystem, allowing you to browse and play your music with any traditional audio player.

Features

• Filesystem Interface: Access your YouTube Music library through a standard filesystem
• Traditional Player Support: Play songs with any audio player that can read files
• Complete Library Access: Browse playlists, liked songs, and albums
• Persistent Authentication: Uses your local browser cookies
• Disk Caching: Caches metadata and audio to improve browsing performance and enable offline playback of previously streamed songs
• On-Demand Streaming: Streams audio directly from YouTube Music servers
• Smart Auto-Refresh: Automatically refreshes your library cache every hour using an intelligent merging approach that preserves existing data and only updates what has changed
• Browser Cookies: Uses browser cookies for authentication to access higher quality audio streams (up to 256kbps) and private playlists

Requirements

• Python 3.10+
• FUSE (Filesystem in Userspace)
• YouTube Music account
• An authenticated YouTube Music browser session
• A browser supported by yt-dlp for cookies, such as Brave, Chrome, or Firefox
• pipx for isolated CLI installation

Installation

System Dependencies

On Debian/Ubuntu, install required system dependencies:

sudo apt install fuse libfuse-dev python3-dev pipx
pipx ensurepath

On Fedora/RHEL:

sudo dnf install fuse fuse-devel python3-devel pipx
pipx ensurepath

On Arch Linux:

sudo pacman -S fuse2 python python-pipx
pipx ensurepath

Restart your shell after pipx ensurepath if ytmusicfs is not found.

High quality YouTube Music extraction needs one supported JavaScript runtime on the ytmusicfs process PATH: node, bun, deno, or quickjs. Use your preferred install method; it does not need to come from the system package manager.

Install YTMusicFS

Install YTMusicFS as an isolated command-line app:

git clone https://github.com/astrovm/ytmusicfs
cd ytmusicfs
pipx install .

Upgrade after pulling new changes:

git pull
pipx install --force .

Authentication Setup

YTMusicFS reads cookies from your browser when you mount with --browser. Log in to YouTube Music in that browser before mounting.

Usage

Command Structure

YTMusicFS uses a command-based structure with the following format:

ytmusicfs <command> [options]

Available commands:

• mount: Mount YouTube Music as a filesystem
• unmount: Unmount the active YouTube Music filesystem
• status: Show saved settings and active mount state
• doctor: Check local dependencies
• config: Show or update saved mount settings
• cache: Inspect or clear the persistent cache
• repair: Replace unavailable liked-song IDs with playable matches
• logs: Show recent log lines (default last 50)
• service: Manage an optional systemd user service

Mount the Filesystem

Create a mount point and mount with browser cookies. This is the normal way to run YTMusicFS because it enables high quality streams and private library access.

mkdir -p ~/Music/ytmusic
ytmusicfs mount --mount-point ~/Music/ytmusic --browser brave

YTMusicFS remembers the last mount point and browser. After the first successful mount, you can use:

ytmusicfs mount

--browser brave tells yt-dlp which local browser profile to read cookies from. Replace brave with your browser if needed. Supported browsers include brave, chrome, firefox, and others supported by yt-dlp.

On mount, YTMusicFS refreshes playlist and album roots immediately. Expensive liked-song refresh runs later in a delayed background worker that waits for the mounted filesystem to be idle, so file managers do not wait on YouTube Music. The /.ytmusicfs/status.json file shows current refresh state.

For debugging or custom paths:

ytmusicfs mount \
  --mount-point ~/Music/ytmusic \
  --browser brave \
  --cache-dir ~/.cache/ytmusicfs \
  --foreground \
  --debug

Browse and Play Music

Once mounted, you can browse the filesystem with your file manager:

ls ~/Music/ytmusic
ls ~/Music/ytmusic/playlists
ls ~/Music/ytmusic/liked_songs

Play music with any audio player:

audacious ~/Music/ytmusic/playlists/MyFavorites/Song.m4a
mpv ~/Music/ytmusic/liked_songs/Artist\ -\ Song.m4a

For Audacious, enable Settings > Advanced > Do not load metadata for songs until played before adding large directories such as /liked_songs. Otherwise Audacious may probe many uncached audio files while building the playlist, which is much slower than loading cached paths and streaming songs when they are played. Also disable Settings > Song Info > Show popup information so Audacious does not request extra song details while browsing.

Unmount

When you're done, unmount the filesystem:

ytmusicfs unmount

To unmount a specific path:

ytmusicfs unmount --mount-point ~/Music/ytmusic

Status and Config

Inspect the current setup:

ytmusicfs status
ytmusicfs config show
ytmusicfs doctor

doctor checks the local FUSE helper, Python FUSE module, JavaScript runtime, and cache directory permissions.

Set saved defaults without mounting:

ytmusicfs config set mount-point ~/Music/ytmusic
ytmusicfs config set browser brave

Cache, Refresh, and Logs

Inspect or clear the local cache:

ytmusicfs cache stats
ytmusicfs cache clear
ytmusicfs cache refresh

cache clear removes metadata and cached audio. cache refresh removes metadata only and keeps cached audio. Both work while YTMusicFS is mounted — the mount process detects and applies the change automatically within a few seconds.

When /liked_songs contains a dead backing video ID, YTMusicFS tries to repair the local cached path automatically by searching for a verified playable replacement. That automatic repair does not change your YouTube Music account.

To also fix the liked state in your account, run:

ytmusicfs repair

Repair works while the filesystem is mounted. The mount process detects and applies the change automatically within a few seconds without needing a remount.

repair only handles tracks already marked unavailable in /liked_songs. For each one, it searches YouTube Music by artist and title, verifies the replacement can stream in the preferred high quality format, then prints the exact account changes before asking for confirmation. If confirmed, it likes the replacement video, removes the like from the unavailable video, and updates the local cache. It skips weak matches and reports failed API calls instead of changing your account.

Show logs:

ytmusicfs logs           # last 50 lines
ytmusicfs logs --tail 20 # last 20 lines
ytmusicfs logs --path    # print log file path

Systemd User Service

Install and manage an optional user service. It uses the saved mount settings, so run one successful ytmusicfs mount --mount-point ... --browser ... first.

ytmusicfs service install
ytmusicfs service start
ytmusicfs service stop
ytmusicfs service status

Filesystem Structure

• /playlists/ - Your YouTube Music playlists
• /liked_songs/ - Your liked songs
• /albums/ - Albums in your library
• /.ytmusicfs/status.json - Lightweight mount status for debugging

Command Line Options

ytmusicfs mount

usage: ytmusicfs mount [-h] [--mount-point MOUNT_POINT] [--cache-dir CACHE_DIR]
                       [--foreground] [--debug] [--browser BROWSER]

Mount YouTube Music as a filesystem

Options:
  -h, --help            Show this help message and exit
  --mount-point, -m MOUNT_POINT
                        Directory where the filesystem will be mounted
  --cache-dir, -c CACHE_DIR
                        Cache directory
  --foreground, -f      Run in foreground
  --debug, -d           Enable debug logging
  --browser, -b BROWSER Browser to use for cookies (e.g., 'chrome', 'firefox', 'brave')

ytmusicfs unmount

usage: ytmusicfs unmount [-h] [--mount-point MOUNT_POINT] [--cache-dir CACHE_DIR]
                         [--debug]

Unmount YouTube Music filesystem

Options:
  -h, --help            Show this help message and exit
  --mount-point, -m MOUNT_POINT
                        Mount point directory. Defaults to the active ytmusicfs mount.
  --cache-dir, -c CACHE_DIR
                        Cache directory
  --debug, -d           Enable debug logging

Other Commands

ytmusicfs status
ytmusicfs doctor
ytmusicfs config show
ytmusicfs config set {browser,mount-point} VALUE
ytmusicfs cache stats
ytmusicfs cache clear
ytmusicfs cache refresh [--cache-dir CACHE_DIR] [--debug]
ytmusicfs repair [--cache-dir CACHE_DIR] [--debug]
ytmusicfs logs [--tail N] [--path] [--debug]
ytmusicfs service {install,start,stop,restart,status} [--debug]

Limitations

• Stream URLs from YouTube Music expire after some time
• Seeking may not be perfectly smooth in all players
• Metadata like album art may be limited depending on your player

Troubleshooting

Authentication Issues

• Log in to https://music.youtube.com in the browser passed to --browser.
• Keep that browser installed and available to yt-dlp.

Playback Issues

• Refresh the local install after pulling changes: pipx install --force .
• Some players may not handle streaming URLs well; try different players
• If audio stops, the stream URL may have expired; simply restart playback
• If a liked song exists in YouTube Music but ytmusicfs reports No such file or directory, its cached video ID may be unavailable. Browse /liked_songs again to let YTMusicFS repair the local cache automatically. Run ytmusicfs repair only when you also want to update your account likes.

Performance Issues

• Keep the cache directory on a fast disk for quicker metadata lookups
• Reduce network calls by browsing directories fully before playing