Create

The create command is used to create new BitTorrent metafiles.

The basic invocation requires only a target directory or file to create a .torrent from.

torrenttools create [OPTIONS] <target>

Either specify all options first or give the target first followed by all options.

Overview

Create BitTorrent metafiles.
Usage: torrenttools create [OPTIONS] target

Positionals:
  target <path>                    Target filename or directory

Options:
  -h,--help                        Print this help message and exit
  -v,--protocol <protocol>         Set the bittorrent protocol to use.
                                    Options are 1, 2 or hybrid. [default: 1]
  -o,--output <path>               Set the filename and/or output directory of the created file.
                                   [default: <name>.torrent]
                                    Use a path with trailing slash to only set the output directory.
  -a,--announce <url>...           Add one or multiple announces urls.
                                   Multiple trackers will be added in seperate tiers by default.
                                   Use square brackets to groups urls in a single tier:
                                    eg. "--announce url1 [url1 url2]"
  -g,--announce-group <name>...    Add the announce-urls defined from an announce group specified in the configuration file.
                                   Multiple groups can be passed. eg. "--announce-group group1 group2"
  -w,--web-seed <url>...           Add one or multiple HTTP/FTP urls as seeds.
  -d,--dht-node <host:port>...     Add one or multiple DHT nodes.
  -c,--comment <string>            Add a comment.
  -p,--private <[on|off]>          Set the private flag to disable DHT and PEX.
  -l,--piece-size <size[K|M]>      Set the piece size.
                                   When no unit is specified block size will be either 2^<n> bytes,
                                   or <n> bytes if n is larger or equal to 16384.
                                   Piece size must be a power of two in range [16K, 64M].
                                   Leave empty or set to auto to determine by total file size. [default: auto]
  -s,--source <source>             Add a source tag to facilitate cross-seeding.
  -n,--name <name>                 Set the name of the torrent. This changes the filename for single file torrents
                                   or the root directory name for multi-file torrents.
                                   [default: <basename of target>]
  -t,--threads <n>                 Set the number of threads to use for hashing pieces. [default: 2]
  --checksum <algorithm>...        Include a per file checksum of given algorithm.
  --no-creation-date               Do not include the creation date.
  --creation-date <ISO-8601|POSIX time>
                                   Override the value of the creation date field as ISO-8601 time or POSIX time.
                                   eg.: "2021-01-22T18:21:46+0100"
  --no-created-by                  Do not include the name and version of this program.
  --created-by <string>            Override the value of the created by field.
  --include <regex>...             Only add files matching given regex to the metafile.
  --exclude <regex>...             Do not add files matching given regex to the metafile.
  --include-hidden                 Do not skip hidden files.
  --io-block-size <size[K|M]>      The size of blocks read from storage.
                                   Must be larger or equal to the piece size.

Options

-v,--protocol

Set the bittorrent protocol to generate a metafile for. Available options are: 1, 2 or hybrid. The default options is to create v1-only metafiles. 1 and 2 can be prefixed with a v.

torrenttools create --protocol v1 test-dir
torrenttools create -v1 test-dir
torrenttools create -vhybrid test-dir

-o,--output

Set the filename and/or output directory of the created file. If no options are given the torrent will be written to <name>.torrent in the current directory, with name the name of target directory or file.

torrenttools create test-dir --output "my-name.torrent"

Use a path with trailing slash to only set the output directory and keep the name to the default

torrenttools create test-dir --output ~/torrents/

Will create a torrent with full path ~/torrents/test-dir.torrent

-a,--announce

Add one or multiple announces urls.

torrenttools create test-dir --announce "url1" "url2"

Multiple trackers will be added in seperate tiers by default. Use square brackets to groups urls in a single tier.

torrenttools create test-dir --announce "[url1 url2]"

`` -g,–announce-group``

Add all announces inside a tracker group to the metafile.

torrenttools create test-dir --announce-group "public-trackers"

--stdout

Write the torrent to the standard output. Normal output will be redirected to stderr.

-w,--web-seed

Add one or multiple HTTP/FTP urls as seeds.

-d,--dht-node

Add one or multiple DHT nodes. The expected format is <host>:<port>.

torrenttools create test-dir ---dht-node "127.0.0.1:8686" "192.168.0.0:9999:

-c,--comment

Add a comment.

-p,--private

Set the private flag to disable DHT and PEX. When no options are given this will enable the private flag. Pass “on” or “off” to override the defaults when using supported trackers .

-l,--piece-size

Set the piece size. When no unit is specified block size will be either 2^<n> bytes or <n> bytes if n is larger or equal to 16384. Piece size must be a power of two in range 16K to 64M. Leave empty or pass “auto” to determine by total file size.

Piece size as a power of two. (2**20 = 1MiB)

torrenttools create test-dir --piece-size 20

Piece size as a size in bytes. (65536 = 64 KiB)

torrenttools create test-dir --piece-size 65536

Piece size with unit

torrenttools create test-dir --piece-size 2M
torrenttools create test-dir --piece-size 2MiB
torrenttools create test-dir --piece-size "2 MiB"

-s,--source

Add a source tag to facilitate cross-seeding.

-n,--name

Set the name of the torrent. The default option to use the basename of the target.

Warning

This options changes the filename inside the torrent for single file torrents or the root directory name for multi-file torrents. Use with caution.

-t,--threads

Set the number of threads to use for hashing pieces. Default is 2.

Note

The hashing bottleneck is usually the maximum sequential read speed of you storage device so only increasing this as long as you notice a difference. Increasing this usually makes sense only for very fast SSD or Optane storage.

--checksum

Include a per file checksum for given algorithm. The possible options depend on the cryptographic library used. All possible options can be listed with:

torrenttools --checksum-algorithms

Note

This is only useful for v1 metafiles. v2 and hybrid metafiles have per-file merkle roots which makes this options redundant.

--no-creation-date

Do not include the current date in the creation date field.

--creation-date

Override the value of the creation date field as an ISO-8601 time or POSIX time string.

torrentools create test-dir --creation-date "2021-01-22T18:21:46+0100"
torrentools create test-dir --creation-date 1611339706

--no-created-by

Do not include the name and version of this program.

--created-by

Override the value of the created by field.

torrenttools test-dir --created-by "Me"

--include-hidden

Do not skip hidden files when scanning the target directory for files.

torrenttools create test-dir --include-hidden

--include

torrenttools create test-dir --include "

Note

When the include pattern matches hidden files these will be included in the torrent even if –include-hidden was not specified.

--exclude

Do not add files matching given regex to the metafile. Multiple patterns can be specified. When used together with –include, the include patterns will be evaluated first and further filtered by the exclude patterns.

--io-block-size

The size of blocks read from storage. Set to a large value for disks used heavy load to reduce the number of IO operations per second. This value must be larger or equal to the piece-size.