Metadata-Version: 2.4
Name: threads-dlp
Version: 2.0.0
Summary: Download videos from public Threads posts
Author-email: naedev <nae.devp@gmail.com>
License: Apache-2.0
Project-URL: Homepage, https://github.com/nanaelie/threads-dlp
Project-URL: Repository, https://github.com/nanaelie/threads-dlp
Project-URL: Issues, https://github.com/nanaelie/threads-dlp/issues
Keywords: threads,video,downloader,cli,termux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Operating System :: OS Independent
Classifier: Environment :: Console
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Topic :: Multimedia :: Video
Classifier: Topic :: Utilities
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests<3,>=2.31.0
Requires-Dist: urllib3<3,>=1.26
Dynamic: license-file

# threads-dlp

[![Python 3.9+](https://img.shields.io/badge/python-3.9%2B-3776AB?logo=python&logoColor=white)](https://www.python.org/)
[![Termux](https://img.shields.io/badge/Termux-supported-1f7a5c?logo=android&logoColor=white)](https://github.com/termux/termux-app)
[![License](https://img.shields.io/github/license/nanaelie/threads-dlp)](LICENSE)
[![GitHub stars](https://img.shields.io/github/stars/nanaelie/threads-dlp?style=social)](https://github.com/nanaelie/threads-dlp)

`threads-dlp` is a command-line tool for downloading videos from publicly viewable Threads posts. It runs on Linux, macOS, Windows, and Android through Termux. It uses Python and HTTP requests; Chrome, Selenium, and a Threads account are not required.

## Features

- Accepts Threads post links on `threads.com` and `threads.net`, including `/t/` and `/share/` links
- Finds the video attached to the requested post and selects its highest-resolution progressive MP4
- Streams downloads to disk and displays progress in an interactive terminal
- Creates the output folder when needed and avoids overwriting existing files
- Removes incomplete downloads when a network or disk error occurs

Only public posts are supported. Private, deleted, age-restricted, or otherwise unavailable posts cannot be downloaded. The tool does not log in or accept account credentials.

## Requirements

- Python 3.9 or newer
- An internet connection

## Install

Install from a repository checkout:

```bash
git clone https://github.com/nanaelie/threads-dlp.git
cd threads-dlp
python -m pip install .
```

## Termux on Android

Install Python in Termux, create an isolated environment, and install the package:

```bash
pkg update
pkg install python git
git clone https://github.com/nanaelie/threads-dlp.git
cd threads-dlp
python -m venv .venv
. .venv/bin/activate
python -m pip install .
```

To save into Android shared storage, grant Termux storage access once and choose the Downloads folder:

```bash
termux-setup-storage
threads-dlp --url "https://www.threads.com/@username/post/POST_ID" --output ~/storage/downloads/Threads
```

Termux storage access is optional. You can also save to a folder inside Termux's private files.

## Usage

```bash
threads-dlp --url "https://www.threads.net/@username/post/POST_ID"
```

Choose an output folder with `--output` or `-o`:

```bash
threads-dlp --url "https://www.threads.com/t/POST_ID" --output "./videos"
```

The saved filename uses the post ID, for example `POST_ID.mp4`. If that file already exists, the tool uses the next available name, such as `POST_ID-1.mp4`.

Show the available options or installed version:

```bash
threads-dlp --help
threads-dlp --version
```

## Troubleshooting

- **No public video was found:** check that the link points to a post containing a video and that it opens without signing in.
- **The video source returned an error:** video links can expire. Run the command again to extract a fresh link.
- **Permission denied:** choose a folder Termux can write to. For Android shared storage, run `termux-setup-storage` and use `~/storage/downloads`.
- **Threads changed its page:** extraction relies on data embedded in Threads' public web pages. A change to that page format can require an update to this tool.

## Project layout

```text
threads-dlp/
├── README.md
├── CONTRIBUTING.md
├── LICENSE
├── pyproject.toml
├── requirements.txt
└── threads_dlp/
    ├── __init__.py
    ├── __version__.py
    ├── cli.py
    ├── downloader.py
    ├── errors.py
    ├── extractor.py
    ├── http_client.py
    ├── make_out_path.py
    └── models.py
```

## License

This project is licensed under the Apache License 2.0. See [LICENSE](LICENSE).
