Install a Release

This is the easiest way to use OperaLibre. You do not need Rust, Node.js, Xcode, or programming experience.

One-line install on macOS and Linux

Open the Terminal app and paste this:

curl -fsSL https://raw.githubusercontent.com/DonovanMontoya/OperaLibre/main/script/install.sh | sh

The installer walks you through the whole setup:

It detects whether you are on an Intel or Apple Silicon Mac, or on Intel/AMD or ARM Linux, and picks the matching combined package from the newest release.
It asks where to install OperaLibre. The default is a new OperaLibre folder in your home folder.
It asks which folder holds your audiobooks. Press Return to use the folder inside the installation, or type the path of a library you already have.
It asks whether OperaLibre should be reachable only from this computer (local) or from phones and other devices on your trusted home network (lan).
It downloads the package, checks it against the published SHA256SUMS.txt digest, and stops without installing anything if the digest does not match.
It offers to set up the optional Audible import, then asks whether you would like to sign in with Libation during setup. Answer n to either question to skip that step and finish it later.
It writes your answers into server.config, clears the macOS download quarantine, and starts the server in the background.

When it finishes, open the address it prints — usually http://localhost:4920 — and create the administrator account.

Running the same command again updates an existing installation in place. It stops the running server and waits for it to exit, copies the new files into a staging folder beside the installation, and only then swaps them into place, so a download or copy that fails part-way leaves the old version untouched. Your data folder, audiobooks folder, and server.config settings are kept.

The installer warns when it is run as root: OperaLibre needs no privileges, and a server running as root turns any media-parser bug into a system compromise. In a terminal it asks before continuing; with --yes it only prints the warning. Prefer the dedicated account and operalibre.service unit described in Deployment.

Useful options, passed after sh -s --:

curl -fsSL https://raw.githubusercontent.com/DonovanMontoya/OperaLibre/main/script/install.sh \
  | sh -s -- --dir ~/OperaLibre --library ~/Audiobooks --mode lan --yes

Option	What it does
`--dir PATH`	Install into `PATH` instead of `~/OperaLibre`
`--library PATH`	Use `PATH` as the audiobook library folder
`--version VERSION`	Install a specific release, such as `0.3.4`
`--mode local` or `--mode lan`	Choose network access without being asked
`--server-only`	Install the API and media server without the bundled web app
`--libation`	Set up the Audible import and offer guided sign-in (also on a later installer run)
`--libation-path PATH`	Use the Libation CLI at `PATH`
`--no-libation`	Skip the Audible import question entirely
`--yes`	Accept installation defaults without questions; skip interactive Audible sign-in
`--no-start`	Install without starting OperaLibre
`--help`	List all options

The environment variables OPERALIBRE_DIR, OPERALIBRE_LIBRARY, OPERALIBRE_VERSION, OPERALIBRE_MODE, OPERALIBRE_LIBATION_PATH, and OPERALIBRE_SERVER_ONLY=1 set the same values as the matching options, which is convenient for scripted installs.

Setting up the Audible import during install

If you say yes to the Audible import, the installer handles Libation for you:

It first looks for a Libation you already have — on PATH, in /Applications/Libation.app on macOS, or in /usr/lib/libation or /opt/Libation on Linux — and offers to use it.
If there is none, it offers to download the newest official Libation release for your computer and unpack it into a libation folder inside your OperaLibre installation. Nothing is installed system-wide and no administrator password is needed, so removing it later means deleting that one folder.
You can also type the path of a Libation command-line program yourself, or press Return to skip.

Once Libation is ready, the installer asks Would you like to sign in to Audible with Libation during setup? Press Return for yes. There is no need to find or launch Libation yourself:

Enter the email address you use with Audible and choose the country code for the Audible store where you bought your books. The installer explains the choices.
Open the link Libation prints in your browser. On a server without a browser, you can open it on another computer or your phone.
Sign in on Amazon’s page and complete any verification it requests. Your password is entered only on Amazon’s page.
Copy the entire address from your browser’s address bar, return to Terminal, and paste it when Libation asks for a URL. A final page saying it does not exist is normal. Treat this address like a password and do not share it.

The installer uses the same Libation settings folder that OperaLibre will use, so your account is available after setup. Sign in to OperaLibre as the administrator and open Audible; choose Refresh Audible if your books have not appeared yet. This setup connects your account; it does not download all your audiobooks.

You can decline sign-in or press Return at the email or URL prompt to cancel. If sign-in fails, the installer offers a retry and can still finish installing OperaLibre. When sign-in is skipped, it prints a command with the correct program and settings paths to use later. Runs with --yes or without an interactive terminal always skip sign-in.

Running the installer again preserves your existing Audible configuration and does not prompt for sign-in unless you explicitly pass --libation or --libation-path. See Libation / Audible Import for the rest of the workflow.

Headless servers

--server-only installs the same package without its web app and desktop launchers, for a machine that serves the frontend separately (or not at all):

curl -fsSL https://raw.githubusercontent.com/DonovanMontoya/OperaLibre/main/script/install.sh \
  | sh -s -- --server-only --dir /srv/operalibre --library /srv/audiobooks --mode lan --yes

The installer leaves out the Open/Stop launchers and writes two helper scripts beside the server instead — start-operalibre.sh runs it in the background and records its process ID in data/operalibre-server.pid, and stop-operalibre.sh stops it. web_dist_dir is left blank, which is what makes an installation server-only; point a separately hosted frontend at the API and list its address in allowed_origins, or set web_dist_dir to a folder holding the frontend release package. To run it as a system service instead, see Deployment and the operalibre.service unit in the repository.

Re-running the installer on an existing folder keeps whichever kind is already there. Installing the other kind requires a different --dir. To turn a downloaded package into a server-only installation by hand, set web_dist_dir = (blank) in its server.config and start it with ./start.sh, or start.cmd on Windows.

Windows is not covered by the installer. Follow the manual steps below, which also work on macOS and Linux if you would rather download the package yourself.

1. Download the complete package

Open the OperaLibre releases page, choose the newest release, and expand Assets if the downloads are hidden.

Most people should download a filename containing combined:

Your computer	Filename contains
Windows PC	`combined-windows-x64.zip`
Apple Silicon Mac (M1, M2, M3, M4, or newer)	`combined-macos-arm64.tar.gz`
Intel Mac	`combined-macos-x64.tar.gz`
Normal Intel/AMD Linux computer	`combined-linux-x64.tar.gz`
64-bit ARM Linux or Raspberry Pi	`combined-linux-arm64.tar.gz`

The combined package includes both pieces OperaLibre needs: the audiobook server and the web app. It is the only server download; to run the server without its web app, see Headless servers. The frontend-only file is for hosting the web app separately, including in front of a Jellyfin server.

2. Extract it

Move the download somewhere permanent, such as Documents or Applications, and extract the whole archive. Do not run the start file from inside the ZIP or TAR.GZ preview.

Keep the extracted OperaLibre folder. Your default audiobook library, accounts, passwords, and listening progress live inside it.

3. Start OperaLibre

Windows

Double-click Open OperaLibre.exe. It starts OperaLibre in the background and opens your browser. If Windows Defender Firewall asks, allow OperaLibre on Private networks. You do not need to allow public networks.

macOS

Double-click Open OperaLibre.app. It starts OperaLibre in the background and opens your browser.

The downloads are not Apple-notarized yet. If macOS blocks the first launch:

Open the Terminal app.
Type xattr -dr com.apple.quarantine , including the space at the end.
Drag the extracted OperaLibre folder into the Terminal window.
Press Return, then double-click Open OperaLibre.app again.

Linux

Double-click open-operalibre. If your file manager does not run executable files when they are double-clicked, open a terminal in the extracted folder and run:

./open-operalibre

If the browser does not open automatically on any platform, open http://localhost:4920.

The launcher exits after OperaLibre is ready. No command or Terminal window needs to remain open, and closing the browser does not stop the server. Use the same Open action whenever you want to return.

Stop OperaLibre

You can normally leave the server running in the background. Before moving its folder, changing important settings, or installing an update, use the included Stop action:

Windows: Stop OperaLibre.exe
macOS: Stop OperaLibre.app
Linux: stop-operalibre

Starting it again is as simple as using the Open action.

4. Create the administrator

The first page asks for the initial administrator name and password. The administrator can upload books, rescan the library, and create accounts for other readers.

Use a password you can remember. See Users & Accounts for household accounts and password recovery.

The standard install remains the small playback server. If you want OperaLibre to create sentence-level follow-along timing, the owner can later open Administration → Experimental features and install the separate readalong sync add-on. Installing it is optional; playback and imported .sync.json maps do not need it.

5. Add audiobooks

The simplest method is:

Sign in as the administrator.
Choose Upload audiobook.
Enter the book name.
Select one M4B or other audio file, or select all audio tracks for a multi-file book.
Wait for the upload and automatic library scan to finish.

Uploads are limited to 20 GiB by default. Administrators can change the upload and generated-download limits in server.config; see Configuration.

You can also copy audiobooks into the package’s audiobooks folder, then choose Rescan library. See Library Layout if you want covers, chapters, or readalong files to be matched automatically.

Use an existing audiobook folder

Stop OperaLibre and open server.config in a plain text editor. Change:

library_root = audiobooks

to the full path of your existing folder:

# Windows
library_root = C:\Users\YourName\Audiobooks

# macOS
library_root = /Users/YourName/Audiobooks

# Linux
library_root = /home/yourname/Audiobooks

Save the file and start OperaLibre again.

Listen on a phone or another computer

The secure default listens only on the server computer. For a trusted home network or private VPN, set deployment_mode = lan and leave host blank in server.config, restart OperaLibre, and connect the other device to that same trusted network. Then open:

http://SERVER-COMPUTER-IP:4920

The server computer’s local IP usually looks like 192.168.1.25 or 10.0.0.25. See Use it on a phone or tablet for installing the web app on the home screen.

Do not expose this plain HTTP address directly to the public internet. Remote access requires the HTTPS setup described in Deployment.

Back up your library

Back up these folders from the extracted combined package:

data — reader accounts, passwords, progress, and generated sync maps
audiobooks — books uploaded into the default library

If library_root points somewhere else, back up that audiobook folder instead.

Update to a newer release

On macOS and Linux, running the one-line installer again is the simplest update. It stops the server and waits for it to exit, stages the newest release beside the installation before replacing the old files, and preserves data, audiobooks, and server.config.

OperaLibre checks the latest release’s signed update manifest when an administrator opens Administration. Every administrator sees an update banner when a newer server is available. An owner can choose Update server to download the package for the server computer, verify its release signature and SHA-256 digest, install it, restart OperaLibre, and reconnect the page.

Stable and nightly

The owner can choose Stable or Nightly under Administration → Software versions → Server update channel. Stable is the default for stable installations and is recommended for everyday listening. Nightly contains recent changes from main and may have bugs. New nightlies are built once a day when the source has changed.

Choosing a channel checks its available release. Review the version and choose Switch and restart to install it; changing the selection alone does not replace the running server. The server and bundled web app switch together. Your server address, library, accounts, settings, and listening progress stay in place. Other connected readers may briefly lose their connection during the restart. Phone and desktop client releases and the optional sync add-on keep their own update paths.

To return, choose Stable and install the offered release, even if its version is lower. Only releases with compatible data formats can be installed this way. If compatibility cannot be confirmed, OperaLibre leaves the current installation running and explains why the switch is unavailable. It does not restore an old database and discard progress made on nightly.

Update to a stable release that includes the channel selector before trying nightly. If no nightly has been published yet, select Stable again. The one-line installer targets stable; use Administration to update or switch an existing nightly installation. Manually replacing binaries bypasses these checks.

Under the hardened operalibre.service unit from deployment the install folder is read-only to the service, so the in-app updater is disabled. Either update manually and restart the service, or explicitly adopt the managed-update systemd templates. Making the folder writable alone is not sufficient: the updater must survive the old server’s exit, and supervision must resume only after health checks or rollback finish. Do not use a watcher on VERSION.txt.

Published packages also receive GitHub build-provenance attestations after the release workflow verifies that the source commit belongs to main, runs the Rust and web tests, lints Rust, and audits production dependencies. To verify a package manually with GitHub CLI, run gh attestation verify FILE --repo DonovanMontoya/OperaLibre. The in-app updaters (the server’s and the macOS app’s) read one file from each release, operalibre-manifest-v1.json, which lists every package with its address, size and SHA-256 and is signed with an Ed25519 key built into OperaLibre. A manifest without a valid signature is refused, and a package that does not match its manifest entry is never installed. SHA256SUMS.txt and the provenance attestation cover packages you download yourself. How the manifest works, and how it can change without stranding older installations, is described in Update manifest. Provenance verification is an additional manual check for security-sensitive installations.

Automatic install is available for managed release installations, with or without the web app. It preserves data, audiobooks, and server.config, so deployment profiles and custom paths survive upgrades. Configs from older versions remain compatible: a non-loopback host with no profile is inferred as lan. Combined updates replace the server, bundled web app, and launchers together; server-only updates replace only the server and leave a separately hosted frontend untouched. The prior managed files remain under update-backups inside data_dir for rollback; if the new server exits during startup, the launcher restores and starts the previous version automatically. A new server that is still scanning a large library when the launcher’s wait runs out is left running, not rolled back.

New configuration keys use secure defaults when they are absent, so an existing managed installation does not need a manual config migration after an automatic update. Add the keys from server.config.example only when you want to override those defaults.

The browser frontend is tracked separately. When a newer standalone frontend package is available, an owner can choose Update frontend to verify and replace only the served web files. The server and playback keep running, the previous frontend is copied to data/update-backups, and the Administration page reloads into the new bundle.

Custom source deployments and system services still show the available version and release-notes link, but must be updated manually:

Stop OperaLibre.
Download and extract the new combined package into a new folder. For a server-only installation, also blank web_dist_dir in its server.config.
Copy the old data folder into the new package, replacing the empty one.
If you used the default library, copy the old audiobooks folder into the new package too.
If you edited server.config, copy your settings into the new file.
Start the new package and confirm your readers, progress, and books appear.
Keep the old folder until you know the update works.

Do not extract an update directly over a running installation. Keeping the old folder makes it easy to go back.