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:

  1. 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.
  2. It asks where to install OperaLibre. The default is a new OperaLibre folder in your home folder.
  3. 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.
  4. It asks whether OperaLibre should be reachable only from this computer (local) or from phones and other devices on your trusted home network (lan).
  5. It downloads the package and checks it against the release’s signed update manifest and its SHA256SUMS.txt digest, and stops without installing anything if either does not match. Checking the signature needs OpenSSL 1.1.1 or later. The openssl built into macOS cannot, so on a Mac without Homebrew’s openssl@3 the installer says the signature was not checked and relies on the digest alone, which catches a damaged download but not a replaced one. Releases before 0.4.6 have no signed manifest, so where the signature can be checked they cannot be installed this way.
  6. It offers to set up the optional Audible import. Answer n to skip it and set it up later.
  7. 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 without being asked
--libation-path PATH Use the Libation CLI at PATH
--no-libation Skip the Audible import question entirely
--yes Accept installation defaults without questions
--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.

The installer prepares Libation; you connect your Audible account in OperaLibre afterwards. Sign in as the administrator, open Get books → Audible, and choose Connect Audible. See Connect or reconnect an account. Connecting an account does not download all your audiobooks.

Running the installer again preserves your existing Audible configuration. 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 from an OperaLibre 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:

  1. Open the Terminal app.
  2. Type xattr -dr com.apple.quarantine , including the space at the end.
  3. Drag the extracted OperaLibre folder into the Terminal window.
  4. 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.

Launcher environment

These variables affect the Open launcher. For the data folder and the port, a value in server.config still wins, for the launcher and for the server it starts. They are separate from the installer’s variables above.

Variable Effect
OPERALIBRE_NO_BROWSER Set to any value, such as 1, to start the server without opening a browser.
OPERALIBRE_DATA_DIR Data folder used when data_dir is absent or blank. Relative paths are resolved from the installation folder. The default is data beside the server. The launcher writes server.log and the process id file here.
PORT Port used when port is absent or blank. The launcher waits for this port and opens it in the browser. The default is 4920.

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 → Experiments and install the separate readalong sync add-on. Installing it is optional; playback and EPUB reading work without it. Sentence following requires an enabled experiment and an aligned map, including when the map was imported rather than generated on this server.

5. Add audiobooks

The simplest method is:

  1. Sign in as the administrator.
  2. Choose Upload audiobook.
  3. Enter the book name.
  4. Select one M4B or other audio file, or select all audio tracks for a multi-file book.
  5. 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

The owner can export accounts, permissions, progress, reading history, and metadata without stopping the server under Administration → Overview → Server backup. This portable export does not include the books or all files in the data folder.

For a complete copy, stop OperaLibre and back up these items from the extracted combined package:

  • data — reader accounts, passwords, progress, and generated sync maps
  • audiobooks — books uploaded into the default library
  • server.config — your deployment profile and paths

If library_root or data_dir points somewhere else, back up those folders instead. Include hidden OperaLibre cover files in the library copy. Restart after copying, keep the backup private, and see Backups for restore behavior and moving sync maps and schedules.

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. Those connections trust the Mozilla roots bundled with the server. A network that intercepts HTTPS is described in Troubleshooting.

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. Before installing, the launcher also makes two copies of the database and the library identity file there, one to keep and one ready to put back, so it needs free space of about twice the size of operalibre.db. Rollback then needs no more space, even if the new version filled the disk. If the copies cannot be made, the update stops and the current version keeps running. Until the new version has finished its first scan and the launcher has confirmed the update, it accepts no changes: apps and Audiobookshelf clients see a server that is still starting, keep listening progress on the device, and send it once the update is confirmed. The web app itself still loads meanwhile. If the new server exits during startup, cannot load the library, or has not finished its first scan within ten minutes, the launcher restores and starts the previous version automatically. When the new version had already upgraded the data to a format the previous one cannot read, the saved copy is put back as well, and the new version’s own copy is kept in a failed-data folder under update-backups in case you need anything from it. Otherwise the data is left as it is. The pre-update data copies are deleted once a server starts successfully; any failed-data is kept for recovery. Updating to a version older than this protection (a downgrade) works as before: changes made while it is starting can be lost if it then fails.

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.

After a successful update, OperaLibre keeps only the latest completed backup for each of the server, standalone frontend, and follow-along add-on. Unfinished updates, recovery material, and backups from older versions without a completion marker are left alone. Automatic cleanup errors are logged and do not fail an otherwise successful update.

To reclaim space from older backups manually, stop OperaLibre with the included Stop action and open update-backups inside your configured data_dir. Keep the newest backup for each component. Delete an older folder only after confirming its update succeeded and you no longer need it. Leave any folder containing data, restore-required, restore-pending, failed-data, or failed-data.partial until you have recovered or separately saved anything you need; these can be the only copies available after a failed update. Folders without a .completed file are not automatically removed, so check them individually rather than deleting by age.

Combined installations update their server and bundled web app together; a frontend-only install is unavailable for those packages. For a standalone frontend served by the server from web_dist_dir, an owner can choose Update frontend when a newer package is available. The server and playback keep running, the previous frontend is copied to update-backups inside data_dir, and Administration reloads into the new bundle. Frontends hosted elsewhere must be updated through that host.

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

  1. Stop OperaLibre.
  2. 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.
  3. Copy the old data folder into the new package, replacing the empty one.
  4. If you used the default library, copy the old audiobooks folder into the new package too.
  5. If you edited server.config, copy your settings into the new file.
  6. Start the new package and confirm your readers, progress, and books appear.
  7. 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.