pytrash 0.3.3

a high level api for handling recycle bins across platforms

pytrash

a high level api for handling recycle bins across platforms

Installation

uv add pytrash

Usage

import pytrash

# pytrash provides a way to move files to the bin, list entries in bin, and restore files from bin.
# create instance of Bin
bin = pytrash.RecycleBin()

# move a file to the bin
bin.recycle(["path/to/file.txt"])

# list entries
bin.entries()

# restore a file from the bin
entry = bin.entries()[0]
bin.restore([entry])

# permanently delete a file from the bin (irreversible!)
bin.purge([entry])

# permanently delete everything in the bin (irreversible!)
bin.empty()

That's it. It doesn't get any simpler than that.

Entries are returned as a list of TrashEntry dataclasses, which contain the following attributes:

TrashEntry(
  name='Screenshot from 2026-06-10 17-35-55.png',
  original_path='/home/nspc911/Pictures/Screenshots/Screenshot from 2026-06-10 17-35-55.png',  # this will be None if entry doesn't contain this info
  deleted_at=datetime.datetime(2026, 6, 28, 11, 31, 17),  # this can be None if entry doesn't contain this info
  size=13075  # shouldn't be None, but it is possible.
)

For now, only the major 3 OSes are supported (Windows, Linux, MacOS). If you want to add support for your OS, feel free to open a PR.

CLI

This also includes a CLI for interacting with the recycle bin

uv tool install pytrash

pytrash trash <file1> <file2> ...  # move files to the bin
pytrash list                       # list entries in the bin
pytrash list --json                # list entries in the bin
pytrash restore <entry1> <entry2> ...  # restore entries from the bin
pytrash purge <entry1> <entry2> ...    # permanently delete entries (asks first; -y to skip)
pytrash empty                          # permanently delete everything (asks first; -y to skip)

This CLI interface is not to be compared with the trashy CLI, it is Rust, it doesn't have the Python Interpreter overhead. This project aims to provide an easy interface for cross platform bins. The CLI is simply a way to make use of it.

Like what I do? Check out similar projects

• multiarchive: a high level api for handling archives across formats