Importarr

Importarr is an Arr-style service for importing manually categorized SABnzbd downloads after SAB reports final completion. It owns one SAB category, defaults to manual, and refuses to import transient Direct Unpack paths or jobs still in SAB queue/post-processing.

Install

Importarr is intended to feel like a small Arr service: deploy the container or systemd service, edit one env file, point SABnzbd category manual at the same completed-download path, then open the web UI.

Docker Compose, recommended

mkdir -p importarr/config
cd importarr
curl -fsSLO https://example.com/importarr/deploy/docker-compose.example.yml
curl -fsSLo importarr.env https://example.com/importarr/deploy/importarr.env.example
${EDITOR:-vi} importarr.env
docker compose -f docker-compose.example.yml --env-file importarr.env up -d

Then open http://host:8765/ or put it behind your reverse proxy. For a local build instead of a published image, run:

docker build -t importarr:local .

systemd / pip install

git clone https://example.com/importarr.git
cd importarr
sudo sh deploy/systemd-install.sh
sudo ${EDITOR:-vi} /etc/importarr/importarr.env
sudo systemctl start importarr.service

The installer creates the importarr system user when needed, installs a virtualenv, and installs the package from the checked-out repository. Override install paths with IMPORTARR_* variables if the defaults do not fit your environment.

For a machine that should stay current with the repository, use the installed repo-upgrade helper:

sudo -n sh /opt/importarr/repo-upgrade.sh

The helper refuses to run when the checkout has uncommitted changes, then performs git pull --ff-only, reinstalls the package from the repo, restarts importarr.service, and prints service status. Use it after changes have been committed and pushed to main.

Installed deployments can expose the same operation through the authenticated API. Configure IMPORTARR_UPDATE_COMMAND when the default sh deploy/repo-upgrade.sh is not correct for the service working directory, and configure IMPORTARR_RESTART_COMMAND when the default systemctl restart importarr.service needs a wrapper such as sudo.

Release-worthy changes should be committed, tagged with SemVer (v0.1.1, v0.2.0, ...), pushed with tags, then installed from the tagged checkout or artifact.

Required setup

1. In SABnzbd, create or confirm category manual.
2. Set its completed folder to the same path mounted as IMPORTARR_DOWNLOAD_ROOT.
3. Set IMPORTARR_SAB_URL and IMPORTARR_SAB_API_KEY_FILE or IMPORTARR_SAB_API_KEY.
4. Mount/configure IMPORTARR_MOVIES_ROOT and IMPORTARR_TV_ROOT read/write.
5. Set IMPORTARR_AUTH_TOKEN unless write endpoints are protected by a reverse proxy.
6. Check GET /health, then inspect /api/preview before running imports.

Safety model

• SAB-managed imports must be in IMPORTARR_SAB_CATEGORY and present in SAB history as Completed with final storage.
• Active queue/post-processing states such as Queued, Repairing, Extracting, and Moving are never ready.
• _UNPACK_, __UNPACK__, _FAILED_, and _ADMIN_ paths are skipped.
• Manual batches are explicit one-time folders under IMPORTARR_DOWNLOAD_ROOT.

API

• GET /health
• GET /api/status
• GET /api/jobs
• GET /api/preview
• GET /api/history
• GET /api/manual-batches
• POST /api/manual-batches with { "path": "relative/or/absolute/path" }
• DELETE /api/manual-batches/{id}
• POST /api/control/start
• POST /api/control/pause
• POST /api/control/stop
• POST /api/control/cancel-current
• POST /api/control/restart
• POST /api/control/update
• POST /api/queue-items/{id}/action with { "action": "retry|ignore|remove" }
• POST /api/import/run-now

Set IMPORTARR_AUTH_TOKEN_FILE or IMPORTARR_AUTH_TOKEN to require Authorization: Bearer <token> for write endpoints.

Development

python3.12 -m venv .venv
. .venv/bin/activate
pip install -e '.[test]'
pytest
uvicorn importarr.main:app --reload

Operations

Importarr intentionally does not document private deployment topology, hostnames, reverse proxies, monitoring, backups, or operator workflows in this repository. Keep those details in your own ops runbooks.

For a systemd install, prefer a normal package install from the checked-out repo over an editable install so the service user does not need read access to your development checkout.

If the service fails, standard systemd diagnostics are usually enough:

sudo systemctl --no-pager --full status importarr.service
sudo journalctl -u importarr.service -n 120 --no-pager