Skip to main content

Getting Started

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


docker run crossseed/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.


Docker users can skip ahead to Scaling Up.

To get started, we'll use the following command:

# 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 \
-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!


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 these command line flags to override the default: --include-episodes --include-non-videos

Scaling Up

Searching like 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 AppData\Local\cross-seed\config.js. Open this file in your editor of choice, and start editing.


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".

The only required options are torznab, torrentDir, and outputDir (see links for details). Once you've configured those, you can try running the app with

cross-seed search

With that command, cross-seed should get started running through a full scan of your torrent directory!

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, and 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, or your qBittorrent BT_backup dir)
  • /cross-seeds - the output dir. People sometimes point this at a watch folder. If you use autotorrent2 you can set it up to read from this folder.

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

version: "2.1"
image: crossseed/cross-seed
container_name: cross-seed
user: 1000:1000 # optional but recommended
- /path/to/config/folder:/config
- /path/to/rtorrent_sess:/torrents:ro # note that this volume can and should be mounted read-only
- /path/to/output/folder:/cross-seeds
command: search

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. Once you've got that set 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 (used above) will scan each torrent you provide and look for cross-seeds, then exit.

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

If you're satisfied by just running cross-seed search every once in a while, and then using autotorrent2 to inject these into your client, then you're done!

If you want to learn more about fully-automatic cross-seeding, keep reading.