Skip to main content

addsong

PyPI version Python versions License Powered by yt-dlp Tagged with ffmpeg

addsong demo

Paste a link and the song shows up in Apple Music.

addsong takes a song name or a YouTube link. It downloads the track, tags it with the title, artist, and cover art, then drops it into Apple Music. No dragging files around, just a single command.

addsong "songname"
addsong "https://www.youtube.com/watch?v=..."

Installation

You need Python 3.11 or newer, plus two tools that do the real work, yt-dlp and ffmpeg. addsong itself is a Python package you install with pipx.

1. Install addsong

pipx install addsong

Don't have pipx yet? Install it first. On macOS run brew install pipx. On Linux run pip install --user pipx (or use your distro's package). On Windows run pip install pipx. Once pipx is set up, run pipx ensurepath and reopen your terminal so addsong is on your PATH.

No pipx? pip install --user addsong works too.

2. Install yt-dlp and ffmpeg

These do the downloading and tagging. Pick the command for your system.

  macOS

brew install yt-dlp ffmpeg

  Linux and WSL

sudo apt-get install -y ffmpeg && pipx install yt-dlp

On other distros use your package manager for ffmpeg. yt-dlp can come from pipx or pip.

  Windows (PowerShell)

winget install yt-dlp.yt-dlp Gyan.FFmpeg

3. Check it

addsong --version

Updating

pipx upgrade addsong

With pip instead of pipx, run python -m pip install --user --upgrade addsong.

Shell Completions

addsong can print a completion script for your shell. Source it or save it to your shell's completion directory.

source <(addsong --print-completion bash)      # bash
addsong --print-completion zsh  > ~/.zsh/completions/_addsong   # zsh
addsong --print-completion fish > ~/.config/fish/completions/addsong.fish  # fish

See your shell's docs for where completion files go.

Your First Song

addsong "songname"

addsong shows what it found so you can fix mistakes before saving.

  Review track ♪
  Artist: Artist Name
  Title:  Song Title

  [Enter] Add  ·  [E] Edit  ·  [S] Skip
  ❯

Press Enter and the song lands in Apple Music a second later.

Commands

Command What it does
addsong "name" Add the top search result
addsong "<link>" Add a specific video
addsong --results 3 "name" Add the top 3 search results
addsong --playlist "<link>" Add a whole playlist
addsong --from list.txt Add every link in a file
addsong subscribe "<link>" Follow a playlist
addsong sync Add new songs from playlists you follow
addsong list Show playlists you follow
addsong unsubscribe "<link>" Stop following a playlist
addsong forget Forget everything added so it can be re-added

Flags

Flag What it does
-y Don't ask, just add it
--review Always pause to fix the title or artist first
--reimport Add a song again even if you already have it
--dry-run Show what would happen without downloading
--format FMT Output format, m4a (default), mp3, flac, opus
--quality N Audio quality 0 to 10, 0 is best and the default
--notify Pop a desktop notification as each song imports
--quiet / --verbose Show less or more output
--help Full list of commands and options

Set environment variables like ADDSONG_WATCH_DIR to change defaults. Run addsong --help for the full list.

Download Location

On macOS and Windows songs go straight into Apple Music. On Linux they land in ~/Music/addsong/. Point them somewhere else with ADDSONG_WATCH_DIR=/your/folder.

Common Errors

If you see command not found, run pipx ensurepath and reopen your terminal. Still stuck? Repeat the Installation step.

If a song downloads but never shows up, open the Apple Music app and keep it open while adding (macOS or Windows).

If a download fails, update yt-dlp, then retry with --verbose to see why.

Metadata

Release files for addsong 1.0.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for addsong 1.0.1
File Size Uploaded Provenance Actions
addsong-1.0.1.tar.gz 809.8 kB With provenance Details for addsong-1.0.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for addsong 1.0.1
File Interpreter ABI Platform Actions
addsong-1.0.1-py3-none-any.whl Python 3 none any Details for addsong-1.0.1-py3-none-any.whl

Total release size: 845.7 kB

Release files / addsong-1.0.1.tar.gz

Download URL addsong-1.0.1.tar.gz
Size 809.8 kB
Tags Source
SHA-256 checksum
How to use checksums
306f71a28aa30ad008f95011f75dbc3b55907809809bc6efbfeeb1d653354df8
BLAKE2b-256 checksum
How to use checksums
d9e1fd937cfd9f0b940793f0392dfaf7a1c70a5814db79fc7f7bb227a6848b60
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 Jul 15, 2026.

Transparency log

Release files / addsong-1.0.1-py3-none-any.whl

Download URL addsong-1.0.1-py3-none-any.whl
Size 35.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
55acfb8196b49d5ce096cf2a52f976ab3dd8bc24d8a327bc6dbf3a34a47a7a00
BLAKE2b-256 checksum
How to use checksums
ed9f39cddd60d278b54519b7c2e2685dc2b27a7169128884a5ad29bac520c10b
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 Jul 15, 2026.

Transparency log

Security for addsong 1.0.1

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.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for addsong-1.0.1.tar.gz

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 Jul 15, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.0.1 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page