addsong
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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.