Skip to main content

Getting Started

Introduction​

Cross-seeding is the term used for downloading a torrent from one tracker and then using that data to seed across different trackers. Generally, this is not against the rules, but you should always check and abide by your trackers' rules.

Since you already have the torrent's files, this results in zero download and instant seeding. This is a great way to build ratio (especially on your new trackers) and contribute to the torrenting community.

info

This software is designed to work mainly with private trackers. If you are attempting to cross-seed on public trackers, please see our FAQ entry for details before proceeding.

note

The primary documentation for v6 of cross-seed during pre-release is located here in the v6 migration guide. Please refer to this guide if you are using v6 and have questions about the changes. Set up and basic configurations described elsewhere in this documentation that are not present in the migration guide are still valid.

If you have any questions please feel free to contact us on Discord or the Discussions section of GitHub. There are links located as icons in the top right of every page.

danger

Certain cross-seed configurations can result in downloading an excessive number of torrent files in a short amount of time. Trackers may, as a result, forbid this or require specific settings to minimize this behavior as much as possible.

See this FAQ post for details

Now we will install `cross-seed` and run our first search.

Installation​

tip

If you are not already using Docker, and/or especially if you are on Windows, it is not recommended to install Docker specifically for cross-seed. Use one of the other methods (npm or yarn) which we refer to as running "natively".

with Docker​

docker run ghcr.io/cross-seed/cross-seed --version

with npm​

Requires node 16 or greater.

npm install -g cross-seed
cross-seed --version

with yarn​

Requires node 16 or greater.

yarn global add cross-seed
cross-seed --version

with Unraid​

In Unraid, you can install cross-seed from Docker Hub with the Community Applications app. Check out the Unraid guide for details.

tip

Docker users can skip ahead to Scaling Up.

To get started, you can use CLI.

If you already have a config.js file set up, then you can simply run the following to use those settings:

cross-seed search
tip

Any CLI argument provided will override the settings used in your config.js

For CLI commands, a basic example is below:

# one liner
cross-seed search --torrent-dir /path/to/dir/with/.torrent/files --output-dir . --torznab https://localhost/prowlarr/1/api?apikey=12345
# readable
cross-seed search \
  --torrent-dir /path/to/dir/with/torrent/files \ # folder containing .torrent files
  -o . \ # any directory, cross-seed will put its output torrents here
  --torznab https://localhost/prowlarr/1/api?apikey=12345 # any valid torznab link, separated by spaces

If you were lucky, you've already got your first cross-seed in your current directory!

info

cross-seed, by default, is particular about the contents of torrents you feed it. It will ignore torrents with non-video files in them, and it will ignore torrents that look like single episodes.

Use the command line flags to override any defaults: --include-episodes --include-non-videos

These command line arguments are always configurable in the config.js file (generated with gen-config). You won't have to specify them if they are set unless you wish to override the settings temporarily.

Below we will cover the configuration process.

Scaling Up​

Searching like the above is nice, but it's pretty manual and not very useful in practice. In this section, we'll set up a configuration file. A configuration file is not necessary to use cross-seed, but it makes things a lot easier.

without Docker​

Create and edit your config file​

Start by running the following command.

cross-seed gen-config

After that, you will find an autogenerated config file at ~/.cross-seed/config.js or AppData\Local\cross-seed\config.js. Open this file in your editor of choice, and start editing.

info

The config file uses JavaScript syntax. Each option in the config (and each element in a list) must be separated by a comma, and make sure to wrap your strings in "quotation marks" or array (multiple strings) objects in []'s

The only required options are torznab, torrentDir, and outputDir.

tip

There are many other config options available that you should thoroughly look through to achieve your desired results.

Once you've finished with your config file, the following command can get you started running a full scan of your torrent directory!

cross-seed search

with Docker​

Set up your container​

With Docker, any paths that you would provide as command-line arguments or in the config file should stay hardcoded. Instead, you can mount volumes to the Docker container.

  • /config - config dir (this follows a common Docker convention)
  • /torrents - your torrent input dir
    • usually set to your rTorrent session dir, Deluge state dir, Transmission torrents dir, or your qBittorrent BT_backup dir
  • /cross-seeds - the output dir. People sometimes point this at a watch folder. If you use

Create or open your existing docker-compose.yml file and add the cross-seed service:

version: "2.1"
services:
    cross-seed:
        image: ghcr.io/cross-seed/cross-seed
        container_name: cross-seed
        user: 1000:1000 # optional but recommended
        ports:
            - "2468:2468" # you'll need this for daemon mode only
        volumes:
            - /path/to/config/folder:/config
            - /path/to/torrent_dir:/torrents:ro # your torrent clients .torrent cache, can and should be mounted read-only (e.g. qbit: `BT_Backup` | deluge: `state` | transmission: `transmission/torrents` | rtorrent: session dir from `.rtorrent.rc`)
            - /path/to/output/folder:/cross-seeds
            - /path/to/torrent/data:/data # OPTIONAL!!! this is location of your data (used for data-based searches or linking)
              # will need to mirror your torrent client's path (like Arr's do)
        command: daemon # this enables the daemon, change to search to specifically run a search ONLY
        restart: "no" # make sure to not enable it in search mode, otherwise it will keep rerunning constantly

Create a config file​

When you run the container the first time, it will create a config file at /config/config.js. Open this file in your favorite editor. Since you've already configured your volume mappings, the only required config option is torznab.

tip

There are many other config options available that you should thoroughly look through to achieve your desired results.

Once you set that up, you can run your Docker container and it should get started running through a full scan of your torrent directory!

Next Steps​

cross-seed has two subcommands: search and daemon.

  • search will scan each torrent and dataDir (optional) you provide and look for cross-seeds, then exit.

  • daemon will run indefinitely. It can be configured to run searches periodically, watch RSS, and be triggered to search for newly finished downloads.