# Delete files from Transmission torrents
[](https://github.com/dechamps/transmission_delete_unwanted/actions/)
[](https://pypi.org/project/transmission-delete-unwanted/)
[](https://github.com/psf/black)
[](https://github.com/pylint-dev/pylint)
[](https://slsa.dev/spec/v1.0/levels#build-l3)
`transmission-delete-unwanted` is a tool that makes it possible to delete
specific files from [Transmission][] torrents _after they have been downloaded_,
with correct handling of edge cases such as overlapping pieces.
```text
$ transmission-delete-unwanted --torrent-id 88825ccd2812867852a405409313c5aeb6e9b7dc
>>> PROCESSING TORRENT: "Linux ISOs" (hash: 88825ccd2812867852a405409313c5aeb6e9b7dc id: 42)
Wanted: 3224 pieces (25.2 GiB); present: 13266 pieces (103.6 GiB); present and wanted: 3224 pieces (25.2 GiB); present and not wanted: 10042 pieces (78.5 GiB)
Trimming: Linux ISOs/Debian.iso
Removing: Linux ISOs/Fedora.iso
Removing: Linux ISOs/Arch.iso
All done, kicking off torrent verification. This may take a while...
Torrent verification successful.
```
This package also includes `transmission-mark-unwanted`, a tool that ingests a
list of file names and marks the corresponding files as "unwanted" (i.e. do not
download) in Transmission.
## How to use
**WARNING:** while great care was used to ensure `transmission-delete-unwanted`
will not mess up wanted torrent data (including extensive automated test
suites), the possibility of a data corruption bug cannot be excluded. If your
torrent data is valuable, it is a good idea to **make a backup** before running
the script. You can get rid of the backup as soon as the torrent passes the
automatic verification step.
1. Make sure you have [Python][] installed.
2. Make sure you have [pipx][] installed.
3. Run `pipx install transmission_delete_unwanted`.
- The scripts are now available in your PATH.
4. In Transmission, "uncheck" (i.e. set as unwanted/do not download) the files
that you want to get rid of.
- Sadly the Transmission UI will not let you do this for fully downloaded
files (the checkbox is greyed out). You can either do it manually using
`transmission-remote --no-get`, or use the bundled
`transmission-mark-unwanted` tool.
5. Run `transmission-delete-unwanted`.
- Pass `--help` for options.
- Note the script needs RPC access to your Transmission instance, and it also
needs write access to the downloaded torrent files.
6. The files are now gone!
## What does `transmission-delete-unwanted` do?
For each torrent that contains files that are (at least partially) downloaded
but not wanted, `transmission-delete-unwanted` does the following:
1. It stops (pauses) the torrent.
- This ensures Transmission will not attempt to seed data that the script is
in the middle of deleting.
2. It trims and removes files so that no unwanted torrent pieces remain.
3. It triggers a torrent verification (hash check).
- This is to make Transmission notice that the data is gone, so that it
doesn't attempt to seed it anymore.
4. It resumes the torrent.
## FAQ
### How is this different from just deleting the files by hand?
If you naively just delete the files you don't want, it is almost certain that
your torrent will not pass verification anymore, and Transmission will have to
re-download a few bits and pieces.
This is not a Transmission-specific limitation; fundamentally, it is a
consequence of how torrents work. From a low-level BitTorrent protocol
perspective, a torrent is just a giant continuous blob of data that is split
into equal-sized "pieces", which is the smallest unit of data that can be
verified (hash checked) and made available for seeding. If the torrent contains
multiple files, these are just concatenated together; the torrent metadata
indicates the position of each file within the continuous blob.
Crucially, piece boundaries are not related to file boundaries in any way. This
means that it is possible, and in fact very likely, that some pieces will
_straddle_ a file boundary: that is, some pieces contain both the end of a file
and the beginning of the next file.
If you delete a file whose first and/or last piece overlaps with adjacent,
wanted files, you are _de facto_ corrupting these pieces, and Transmission will
(correctly) see them as such. These pieces cannot be advertised for seeding
anymore and will have to be re-downloaded.
The main value proposition of `transmission-delete-unwanted` is it will not fall
into this trap and will correctly preserve overlapping pieces, while still
deleting the remaining unwanted pieces. The tool is also less error-prone as it
does not involve mapping unwanted files manually.
### What does "trimming" mean, and why is the tool producing `.part` files?
If `transmission-delete-unwanted` is unable to remove a file because it contains
data from overlapping wanted pieces (see previous answer), then it will _trim_
the file instead. Trimming means that the file is replaced by a new file which
only contains data from these overlapping pieces and nothing else, so that most
of the disk space can still be reclaimed.
The `.part` suffix makes it clear that this is not a valid, usable file anymore.
This suffix is recognized by Transmission; in fact, it is the same suffix
Transmission itself uses to mark partially downloaded files if the
`rename-partial-files` Transmission setting is used.
Note that these partial files may _look_ like they are still taking the full
amount of disk space, but that is not actually the case. The partial files
`transmission-delete-unwanted` produces are [sparse files][] - that is, most of
the file is a "hole" and does not actually take up disk space. Use the [`du`
command] to see the actual amount of disk space the file is using.
### I marked a file as unwanted, but `transmission-delete-unwanted` does not remove it!
If `transmission-delete-unwanted` produced a `.part` file instead, see the
previous answer.
There is one rare edge case where `transmission-delete-unwanted` may not remove
nor trim the file even though it is unwanted: if the file is only composed of
wanted pieces - i.e. the file is so small that it is only composed of 1 or 2
pieces _and_ these pieces overlap with wanted files - then there is nothing that
can be done about this file without corrupting wanted pieces. In that case the
script will just leave the file alone.
### Is this safe to run on torrents that are actively downloading?
Yes, and it will behave as you'd expect. Even partially downloaded files can be
cleaned up.
The only caveat is this will result in torrent verification being requested in
the middle of a download, which may(?) cause partially downloaded torrent pieces
to be re-downloaded.
[`du` command]: https://man7.org/linux/man-pages/man1/du.1.html
[pipx]: https://pipx.pypa.io/stable/
[Python]: https://www.python.org/
[sparse files]: https://en.wikipedia.org/wiki/Sparse_file
[Transmission]: https://transmissionbt.com/
Raw data
{
"_id": null,
"home_page": null,
"name": "transmission-delete-unwanted",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "transmission, torrent, bittorrent",
"author": null,
"author_email": "Etienne Dechamps <etienne@edechamps.fr>",
"download_url": "https://files.pythonhosted.org/packages/8a/c7/d6c71e603e0639b4920c2a2d826feae9dbcdcb39590e7e84f9a1abdb0d1c/transmission_delete_unwanted-1.0.tar.gz",
"platform": null,
"description": "# Delete files from Transmission torrents\n\n[](https://github.com/dechamps/transmission_delete_unwanted/actions/)\n[](https://pypi.org/project/transmission-delete-unwanted/)\n[](https://github.com/psf/black)\n[](https://github.com/pylint-dev/pylint)\n[](https://slsa.dev/spec/v1.0/levels#build-l3)\n\n`transmission-delete-unwanted` is a tool that makes it possible to delete\nspecific files from [Transmission][] torrents _after they have been downloaded_,\nwith correct handling of edge cases such as overlapping pieces.\n\n```text\n$ transmission-delete-unwanted --torrent-id 88825ccd2812867852a405409313c5aeb6e9b7dc\n>>> PROCESSING TORRENT: \"Linux ISOs\" (hash: 88825ccd2812867852a405409313c5aeb6e9b7dc id: 42)\nWanted: 3224 pieces (25.2 GiB); present: 13266 pieces (103.6 GiB); present and wanted: 3224 pieces (25.2 GiB); present and not wanted: 10042 pieces (78.5 GiB)\nTrimming: Linux ISOs/Debian.iso\nRemoving: Linux ISOs/Fedora.iso\nRemoving: Linux ISOs/Arch.iso\nAll done, kicking off torrent verification. This may take a while...\nTorrent verification successful.\n```\n\nThis package also includes `transmission-mark-unwanted`, a tool that ingests a\nlist of file names and marks the corresponding files as \"unwanted\" (i.e. do not\ndownload) in Transmission.\n\n## How to use\n\n**WARNING:** while great care was used to ensure `transmission-delete-unwanted`\nwill not mess up wanted torrent data (including extensive automated test\nsuites), the possibility of a data corruption bug cannot be excluded. If your\ntorrent data is valuable, it is a good idea to **make a backup** before running\nthe script. You can get rid of the backup as soon as the torrent passes the\nautomatic verification step.\n\n1. Make sure you have [Python][] installed.\n2. Make sure you have [pipx][] installed.\n3. Run `pipx install transmission_delete_unwanted`.\n - The scripts are now available in your PATH.\n4. In Transmission, \"uncheck\" (i.e. set as unwanted/do not download) the files\n that you want to get rid of.\n - Sadly the Transmission UI will not let you do this for fully downloaded\n files (the checkbox is greyed out). You can either do it manually using\n `transmission-remote --no-get`, or use the bundled\n `transmission-mark-unwanted` tool.\n5. Run `transmission-delete-unwanted`.\n - Pass `--help` for options.\n - Note the script needs RPC access to your Transmission instance, and it also\n needs write access to the downloaded torrent files.\n6. The files are now gone!\n\n## What does `transmission-delete-unwanted` do?\n\nFor each torrent that contains files that are (at least partially) downloaded\nbut not wanted, `transmission-delete-unwanted` does the following:\n\n1. It stops (pauses) the torrent.\n - This ensures Transmission will not attempt to seed data that the script is\n in the middle of deleting.\n2. It trims and removes files so that no unwanted torrent pieces remain.\n3. It triggers a torrent verification (hash check).\n - This is to make Transmission notice that the data is gone, so that it\n doesn't attempt to seed it anymore.\n4. It resumes the torrent.\n\n## FAQ\n\n### How is this different from just deleting the files by hand?\n\nIf you naively just delete the files you don't want, it is almost certain that\nyour torrent will not pass verification anymore, and Transmission will have to\nre-download a few bits and pieces.\n\nThis is not a Transmission-specific limitation; fundamentally, it is a\nconsequence of how torrents work. From a low-level BitTorrent protocol\nperspective, a torrent is just a giant continuous blob of data that is split\ninto equal-sized \"pieces\", which is the smallest unit of data that can be\nverified (hash checked) and made available for seeding. If the torrent contains\nmultiple files, these are just concatenated together; the torrent metadata\nindicates the position of each file within the continuous blob.\n\nCrucially, piece boundaries are not related to file boundaries in any way. This\nmeans that it is possible, and in fact very likely, that some pieces will\n_straddle_ a file boundary: that is, some pieces contain both the end of a file\nand the beginning of the next file.\n\nIf you delete a file whose first and/or last piece overlaps with adjacent,\nwanted files, you are _de facto_ corrupting these pieces, and Transmission will\n(correctly) see them as such. These pieces cannot be advertised for seeding\nanymore and will have to be re-downloaded.\n\nThe main value proposition of `transmission-delete-unwanted` is it will not fall\ninto this trap and will correctly preserve overlapping pieces, while still\ndeleting the remaining unwanted pieces. The tool is also less error-prone as it\ndoes not involve mapping unwanted files manually.\n\n### What does \"trimming\" mean, and why is the tool producing `.part` files?\n\nIf `transmission-delete-unwanted` is unable to remove a file because it contains\ndata from overlapping wanted pieces (see previous answer), then it will _trim_\nthe file instead. Trimming means that the file is replaced by a new file which\nonly contains data from these overlapping pieces and nothing else, so that most\nof the disk space can still be reclaimed.\n\nThe `.part` suffix makes it clear that this is not a valid, usable file anymore.\nThis suffix is recognized by Transmission; in fact, it is the same suffix\nTransmission itself uses to mark partially downloaded files if the\n`rename-partial-files` Transmission setting is used.\n\nNote that these partial files may _look_ like they are still taking the full\namount of disk space, but that is not actually the case. The partial files\n`transmission-delete-unwanted` produces are [sparse files][] - that is, most of\nthe file is a \"hole\" and does not actually take up disk space. Use the [`du`\ncommand] to see the actual amount of disk space the file is using.\n\n### I marked a file as unwanted, but `transmission-delete-unwanted` does not remove it!\n\nIf `transmission-delete-unwanted` produced a `.part` file instead, see the\nprevious answer.\n\nThere is one rare edge case where `transmission-delete-unwanted` may not remove\nnor trim the file even though it is unwanted: if the file is only composed of\nwanted pieces - i.e. the file is so small that it is only composed of 1 or 2\npieces _and_ these pieces overlap with wanted files - then there is nothing that\ncan be done about this file without corrupting wanted pieces. In that case the\nscript will just leave the file alone.\n\n### Is this safe to run on torrents that are actively downloading?\n\nYes, and it will behave as you'd expect. Even partially downloaded files can be\ncleaned up.\n\nThe only caveat is this will result in torrent verification being requested in\nthe middle of a download, which may(?) cause partially downloaded torrent pieces\nto be re-downloaded.\n\n[`du` command]: https://man7.org/linux/man-pages/man1/du.1.html\n[pipx]: https://pipx.pypa.io/stable/\n[Python]: https://www.python.org/\n[sparse files]: https://en.wikipedia.org/wiki/Sparse_file\n[Transmission]: https://transmissionbt.com/\n",
"bugtrack_url": null,
"license": null,
"summary": "Delete unwanted files in a Transmission torrent",
"version": "1.0",
"project_urls": {
"Homepage": "https://github.com/dechamps/transmission_delete_unwanted",
"Issues": "https://github.com/dechamps/transmission_delete_unwanted/issues"
},
"split_keywords": [
"transmission",
" torrent",
" bittorrent"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "770682a28a622e4aa32b562fa6194b929e615da26a74f9736ca47f07e5350915",
"md5": "34499779d1c2f7d03246ae77e16ab039",
"sha256": "eb644b235ae908d6fe3efddbf69b89acac94efe1026ab002bc9a85fe6ad38282"
},
"downloads": -1,
"filename": "transmission_delete_unwanted-1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "34499779d1c2f7d03246ae77e16ab039",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 13061,
"upload_time": "2024-09-15T15:45:28",
"upload_time_iso_8601": "2024-09-15T15:45:28.757089Z",
"url": "https://files.pythonhosted.org/packages/77/06/82a28a622e4aa32b562fa6194b929e615da26a74f9736ca47f07e5350915/transmission_delete_unwanted-1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "8ac7d6c71e603e0639b4920c2a2d826feae9dbcdcb39590e7e84f9a1abdb0d1c",
"md5": "38c1664d9fb4622d4ff8bfad784ab2a8",
"sha256": "2fae81add44afbfa1108f7812d90a33cabb7b05d51ca48d8669e321b95cd001f"
},
"downloads": -1,
"filename": "transmission_delete_unwanted-1.0.tar.gz",
"has_sig": false,
"md5_digest": "38c1664d9fb4622d4ff8bfad784ab2a8",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 24659,
"upload_time": "2024-09-15T15:45:29",
"upload_time_iso_8601": "2024-09-15T15:45:29.791001Z",
"url": "https://files.pythonhosted.org/packages/8a/c7/d6c71e603e0639b4920c2a2d826feae9dbcdcb39590e7e84f9a1abdb0d1c/transmission_delete_unwanted-1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-15 15:45:29",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "dechamps",
"github_project": "transmission_delete_unwanted",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "transmission-delete-unwanted"
}
JSON
