Install

This page covers installing pt-tools with Docker, as a Linux binary or as a Windows binary, then signing in for the first time and what is in the data folder.

Option	Systems	Notes
Docker Compose	Any system that runs Docker	Recommended. Upgrading is pulling a new image
docker run	The same	A single command, handy for trying it out
Linux binary	Linux amd64 and arm64	The install script checks SHA-256; can run under systemd
Windows binary	Windows amd64 and arm64	A PowerShell install script, or unpack it yourself
NAS	1Panel, Unraid and fnOS	Install from the app definitions in deploy/

There is no macOS binary; use Docker on macOS.

This site documents the 1.0 preview. The commands below install the 0.48.0 stable release by default, which does not have the features marked "1.0 preview"; to use them, install a preview release as described in Installing a preview release.

Docker Compose (recommended)

Save this as compose.yml:

services:
  pt-tools:
    image: sunerpy/pt-tools:latest
    container_name: pt-tools
    environment:
      PT_HOST: "0.0.0.0"
      PT_PORT: "8080"
      TZ: "Asia/Shanghai"
      PUID: "1000"
      PGID: "1000"
    ports:
      - "8080:8080"
    volumes:
      - ./data:/app/.pt-tools
    restart: unless-stopped
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"

Then start it:

docker compose up -d

IMPORTANT

Keep /app/.pt-tools on a volume. It holds the database, your settings and the secret.key that encrypts site credentials; if the key is deleted or lost, saved cookies cannot be recovered.

The logging section caps the container's standard output log. Without it, Docker's log file keeps growing for as long as the container runs, which matters on a NAS in particular; see Configuration.

The image is published on Docker Hub (sunerpy/pt-tools) and on GHCR (ghcr.io/sunerpy/pt-tools, with a build attestation); both are the same image. If pulling from Docker Hub is slow where you are, set registry-mirrors in Docker's daemon.json; the image name stays the same.

docker run

docker run -d \
  --name pt-tools \
  -p 8080:8080 \
  -v ~/pt-data:/app/.pt-tools \
  -e TZ=Asia/Shanghai \
  sunerpy/pt-tools:latest

Common environment variables

Variable	Meaning	Default
PT_HOST	Address to listen on	0.0.0.0
PT_PORT	Port to listen on	8080
TZ	Time zone	Asia/Shanghai
PUID, PGID	User and group IDs the program runs as inside the container	1000
PT_ADMIN_USER	Initial admin user name	admin
PT_ADMIN_PASS	Initial admin password	adminadmin
PT_ADMIN_RESET	Set to 1 to reset the admin password to the two values above	Not set
HTTP_PROXY etc.	Proxies; see Configuration	Not set

NAS

The deploy/ folder in the repository has app definitions for 1Panel, Unraid and fnOS. The steps below install from those files directly, without an app store. All three map the data folder to /app/.pt-tools in the container; keep that folder across upgrades and reinstalls, and back up the secret.key inside it.

The container runs as the user given by PUID and PGID, and hands the files under /app to that user on startup. Group ID 100, common on NAS systems, already exists in the image (the users group) and is used as is. This needs image 1.0.0-rc.4 or later: earlier images fail to start when PGID is a group that already exists in the image (the log says addgroup: gid in use).

1Panel

Copy the whole deploy/1panel/pt-tools folder to /opt/1panel/resource/apps/local/pt-tools on the server, refresh the local app list in the 1Panel app store, then install pt-tools and fill in the web port and time zone. Data lives in data/ under the app folder.

Unraid

Download deploy/unraid/pt-tools.xml to /boot/config/plugins/dockerMan/templates-user/my-pt-tools.xml on the flash drive, click Add Container on the Docker page and pick pt-tools from the Template list. The template defaults to PUID=99 and PGID=100 (Unraid's nobody and users), with data in /mnt/user/appdata/pt-tools.

fnOS

Create a Compose project in the fnOS Docker app using the Compose file above. Replace ./data with a folder in a shared folder (for example /vol1/1000/docker/pt-tools) and set PUID and PGID to the owner of that folder (check with ls -n). deploy/fnos is the packaging for the third-party app center fnos-apps.

Linux binary

With the install script

curl -fsSL https://raw.githubusercontent.com/sunerpy/pt-tools/main/scripts/install.sh | sh

The script downloads the latest release and that release's checksums.txt, and refuses to install if the SHA-256 does not match. It installs to ~/.local/bin; two environment variables change that:

• TOOL_VERSION: install a particular version, for example TOOL_VERSION=v0.48.0.
• TOOL_INSTALL_DIR: the folder to install into.

Every release's notes include an install command pinned to that release, ready to copy.

Downloading it yourself

From the releases page, download the archive for your architecture and checksums.txt, check it, then unpack it:

sha256sum -c checksums.txt --ignore-missing
tar -xzf pt-tools-linux-amd64.tar.gz
chmod +x pt-tools
./pt-tools web --host 0.0.0.0 --port 8080

To confirm that an archive was built by this project's release pipeline, verify its build attestation with the GitHub CLI:

gh attestation verify pt-tools-linux-amd64.tar.gz --repo sunerpy/pt-tools \
  --signer-workflow sunerpy/pt-tools/.github/workflows/release.yml \
  --deny-self-hosted-runners

Running it under systemd

Create /etc/systemd/system/pt-tools.service, with your own user and paths:

[Unit]
Description=pt-tools
After=network.target

[Service]
Type=simple
User=your_username
WorkingDirectory=/home/your_username
ExecStart=/usr/local/bin/pt-tools web --host 0.0.0.0 --port 8080
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now pt-tools
sudo journalctl -u pt-tools -f

The data is kept in ~/.pt-tools of the user the service runs as.

Windows binary

In PowerShell:

irm https://raw.githubusercontent.com/sunerpy/pt-tools/main/scripts/install.ps1 | iex

To install a particular version, set $env:TOOL_VERSION = "v0.48.0" first. You can also download pt-tools-windows-amd64.exe.zip from the releases page, unpack it and run:

.\pt-tools.exe web --host 0.0.0.0 --port 8080

The data is kept in the .pt-tools folder in your user folder.

Installing a preview release

The preview releases are the versions marked Pre-release on GitHub Releases, numbered like v1.0.0-rc.N. The latest image tag and the install scripts still install the stable release by default, so name the preview version explicitly. The examples below use v1.0.0-rc.36; replace it with the latest preview on the Releases page.

• Docker: use the image sunerpy/pt-tools:v1.0.0-rc.36 (or ghcr.io/sunerpy/pt-tools:v1.0.0-rc.36) and recreate the container. Previews do not update the latest tag, so change the version yourself when a new preview comes out.
• Linux: curl -fsSL https://raw.githubusercontent.com/sunerpy/pt-tools/main/scripts/install.sh | TOOL_VERSION=v1.0.0-rc.36 sh.
• Windows: set $env:TOOL_VERSION = "v1.0.0-rc.36" first, then run the install command above.
• Mobile app: in current previews its packages are in the same Release as the server; see Mobile app.

The preview releases are for testing and are not recommended for production yet. Before upgrading from the stable release, save the data folder as described in Backing up: a preview migrates the database schema when it starts, so to go back to 0.48.0, restore the data folder you backed up before upgrading.

Signing in for the first time

Open http://your-server:8080 and sign in with the initial account: user name admin, password adminadmin. If you set PT_ADMIN_USER and PT_ADMIN_PASS before the first start, those apply instead.

Change the password straight away in Change password (修改密码). If you forget it, follow "Resetting the admin password" in Configuration.

WARNING

Do not expose pt-tools directly to the internet. For remote access, put it behind a reverse proxy with HTTPS, or reach it over a VPN.

The data folder

Every option uses the same layout:

.pt-tools/
├── secret.key     # the credential encryption key; back it up with the database
├── torrents.db    # SQLite database: settings, task history and cached statistics
├── downloads/     # staged .torrent files
├── backups/       # configuration backups made automatically
└── logs/          # rotated logs

Backing up and restoring are covered in Upgrades and backups.

Next

Once it is running, follow Quick start to add a downloader, your sites and a first RSS feed.