Install & launch¶
The quick way: download a release¶
Builds for Windows, macOS and Linux are on the Releases page:
| System | Pick |
|---|---|
| Windows | …-setup.exe or ….msi to install, or the .zip to run without installing |
| macOS | the .dmg (Apple Silicon) |
| Ubuntu / Debian | the .deb (sudo apt install ./AMP_….deb) |
| Other Linux | the .AppImage (chmod +x, then run it) |
You still need Node.js 18+ on your PATH (see below). The builds aren't
signed: on Windows, SmartScreen warns on first launch ("More info" → "Run anyway"); on macOS,
right-click the app and choose Open the first time.
The rest of this page is for running AMP from the source code.
Prerequisites¶
| Tool | Version | Why |
|---|---|---|
| Python | 3.10+ (3.13 used in CI) | runs the backend |
| Node.js | 18+ (24 used in CI) | builds the frontend, and yt-dlp needs it at runtime to solve YouTube's JavaScript challenges |
| Rust toolchain | stable | builds the Tauri desktop shell (rustup.rs) |
Node.js must be on PATH whenever AMP runs, including the installed app: it is not bundled.
Extra system packages on Linux
Tauri needs WebKitGTK and a few libraries. On Debian/Ubuntu (the list CI uses):
1. Set up the backend¶
All commands run from the amp/ folder of the repository.
requirements.lock pins exact versions that pass the test suite. requirements.txt holds the
looser version ranges it was generated from.
The venv location matters
In development, the desktop app runs the backend with amp/venv's Python. If your
interpreter lives elsewhere, point the AMP_PYTHON environment variable at it.
2. Build the sidecar (once)¶
This builds the backend into a single executable with PyInstaller and copies it to
frontend/src-tauri/binaries/amp-backend-<target-triple>[.exe]. Release builds ship this file.
Tauri refuses to start without it, even in development, where the venv is used instead.
Rebuild it after every dependency upgrade (yt-dlp especially). Add --smoke to also start the
binary and check that it answers, searches and exits cleanly.
3. Run the desktop app¶
On Windows, double-clicking AMP.bat at the repository root does the same (it runs npm install
first if node_modules is missing). The sidecar from step 2 is still needed.
The f## 4. Build the app (optional)
One script builds everything and puts the results in build/ at the repository root:
cd amp
python scripts/build_release.py # executable + installers for this system
python scripts/build_release.py --exe-only # executable only
In build/ |
What |
|---|---|
AMP-1.1.0-<os>-<arch>/ |
AMP[.exe] with amp-backend[.exe] (and WebView2Loader.dll on Windows) next to it. Run AMP directly, nothing to install; keep the files together. |
AMP-1.1.0-<os>-<arch>.zip / .tar.gz |
the same folder, archived |
installers/ |
Windows: .msi and -setup.exe · macOS: .dmg · Linux: .deb and .AppImage |
Options: --bundles deb,appimage (or msi, nsis, dmg…) picks installer types, --smoke
tests the backend executable before packaging, --skip-sidecar reuses the one already built.
On Windows, AMP-build-and-run.bat at the repository root (or --run) rebuilds only what changed,
without installers or archive, then starts the built app: the quick way to try a small change.
A build runs the bundled backend, not your venv, so it works without Python installed. Tauri only builds for the system it runs on; the other systems are built by the Release workflow.
e front instead of opening a second copy. Two backends sharing the same cache folder would delete each other's files.
4. Build an installer (optional)¶
The installers end up in frontend/src-tauri/target/release/bundle/:
| Platform | Output |
|---|---|
| Windows | msi/AMP_1.0.0_x64_en-US.msi and nsis/AMP_1.0.0_x64-setup.exe |
| Linux | deb/… (also built by CI on every push) |
The release app (src-tauri/target/release/amp[.exe]) runs the bundled sidecar rather than
your venv, so it works without Python installed.
Unsigned
The installers aren't code-signed: Windows SmartScreen will warn on first launch.
Updating yt-dlp¶
When YouTube changes something, songs stop playing until yt-dlp catches up. yt-dlp is the one
dependency that isn't capped in requirements.txt, so you can upgrade it on its own:
cd amp
pip install -U "yt-dlp[default]"
python -m pytest backend/tests/test_integration_download.py -m integration -v -s
pip freeze > requirements.lock # only if the test passed
python scripts/build_sidecar.py # the sidecar bundles its own copy
The [default] extra installs yt-dlp-ejs, the JavaScript challenge solver that works with Node.js.