Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/avikekk/JackettSearchBot/llms.txt

Use this file to discover all available pages before exploring further.

​
Prerequisites

Before you begin, ensure you have the following:

Python 3.10+

JackettSearchBot requires Python 3.10 or higher. Check your version with python --version.

uv Package Manager

Install uv for fast dependency management: curl -LsSf https://astral.sh/uv/install.sh | sh

Telegram Bot Token

Create a bot via @BotFather on Telegram to get your bot token.

Jackett Instance

A running Jackett instance (localhost or remote) with an API key.
You’ll also need your Telegram API credentials (API_ID and API_HASH) from my.telegram.org.

​
Installation

1

Clone the Repository

Clone the JackettSearchBot repository and navigate to the directory:
git clone https://github.com/yourusername/JackettSearchBot.git
cd JackettSearchBot
2

Install Dependencies with uv

Use uv to create a virtual environment and install all dependencies:
uv sync
This command automatically:
  • Creates a .venv directory with a virtual environment
  • Installs all dependencies from pyproject.toml
  • Installs tgcrypto on Python 3.10-3.12 (skipped on 3.13+ without C++ tools)
You don’t need to manually activate the virtual environment when using uv run commands.
3

Create Configuration File

Copy the example configuration file and open it for editing:
cp config.env.example config.env
nano config.env  # or use your preferred editor
4

Configure Environment Variables

Fill in your configuration values in config.env:
# Telegram Bot Configuration
TELEGRAM_TOKEN=123456789:ABCdefGHIjklMNOpqrsTUVwxyz
API_ID=12345678
API_HASH=0123456789abcdef0123456789abcdef

# Jackett Configuration
JACKETT_API_KEY=your_jackett_api_key_here
JACKETT_URL=http://localhost:9117

# Authorization
AUTHORIZED_CHAT_IDS=123456789,987654321
OWNER_ID=123456789

# Bot Behavior
MAX_RESULTS=10
REDACT_AFTER_SECONDS=300

# Logging
LOG_FILE_PATH=logs/jackett_bot.log
CONSOLE_LOG_LEVEL=INFO
FILE_LOG_LEVEL=DEBUG

​
Configuration Reference

VariableDescriptionRequiredDefault
TELEGRAM_TOKENBot token from @BotFatherYes-
API_IDTelegram API ID from my.telegram.orgYes-
API_HASHTelegram API hash from my.telegram.orgYes-
JACKETT_API_KEYYour Jackett API keyYes-
JACKETT_URLJackett base URL (with protocol)Yes-
AUTHORIZED_CHAT_IDSComma-separated chat/user IDs with accessNoEmpty
OWNER_IDYour Telegram user ID (for admin commands)Yes-
MAX_RESULTSResults per pageNo10
REDACT_AFTER_SECONDSAuto-redaction timeout for resultsNo300
LOG_FILE_PATHPath for rotating log fileNologs/jackett_bot.log
CONSOLE_LOG_LEVELConsole logging levelNoINFO
FILE_LOG_LEVELFile logging levelNoDEBUG
Never commit config.env to version control! Add it to your .gitignore to prevent accidentally exposing your credentials.

​
Getting Your Credentials

1

Get Telegram Bot Token

  1. Open Telegram and search for @BotFather
  2. Send /newbot and follow the prompts
  3. Choose a name and username for your bot
  4. Copy the bot token provided (format: 123456789:ABCdefGHI...)
2

Get Telegram API Credentials

  1. Visit my.telegram.org/apps
  2. Log in with your phone number
  3. Create a new application
  4. Copy your api_id (numeric) and api_hash (hex string)
3

Get Your Telegram User ID

Get your user ID for the OWNER_ID field:
  1. Send a message to @userinfobot
  2. Copy your numeric ID (this grants you admin access)
4

Get Jackett API Key

  1. Open your Jackett web interface (usually http://localhost:9117)
  2. Find the API Key at the top right corner
  3. Copy the key (it’s displayed next to “API Key:“)

​
Running the Bot

Once configured, start the bot with: 
uv run python main.py
You should see output like this: 
2026-03-03 12:00:00 | INFO | JackettSearchBot | JackettSearchBot initialized.
2026-03-03 12:00:00 | INFO | JackettSearchBot | Logging configured | console=INFO | file=DEBUG | path=/path/to/logs/jackett_bot.log
2026-03-03 12:00:00 | INFO | JackettSearchBot | Initialization complete. Configuration is valid.
2026-03-03 12:00:00 | INFO | JackettSearchBot | Starting bot runtime.
The bot runs in the foreground by default. Press Ctrl+C to stop it gracefully. For production deployments, see the Running guide.

​
Verify Bot Access

Test that everything is working:
1

Find Your Bot

Search for your bot on Telegram using the username you chose in @BotFather.
2

Start the Bot

Send /start to your bot. You should receive:
STATUS: BOT STARTED
If you get ERROR: NOT AUTHORIZED, verify that your user ID is in OWNER_ID or AUTHORIZED_CHAT_IDS.
3

View Available Commands

Send /help to see all available commands:
BOT COMMANDS:

/help - Show this command list.
/start - Verify bot access.
/release <query> - Search releases with pagination.
/release <query> -gp - Search only Golden Popcorn releases.
/r <query> - Short alias for /release.
/check - Check PTP availability (auth required).
/auth [id] - Owner-only temporary authorize.
/unauth [id] - Owner-only remove temporary authorization.
/unauthall - Owner-only clear temporary authorizations.
Let’s perform your first search: 
/release inception
The bot will respond with paginated results: 
SEARCH RESULTS
Query: inception
Page: 1/3 | Total: 25

Title: Inception (2010) 1080p BluRay x264
Age: 2 d
Size: 12.5 GB

Title: Inception (2010) 720p BluRay x264
Age: 2 d
Size: 6.8 GB

...

[Prev] [Next]
Results automatically redact after 300 seconds (configurable via REDACT_AFTER_SECONDS) for privacy.

​
Understanding Pagination

When search results exceed MAX_RESULTS (default: 10), the bot provides inline pagination buttons:
  • Prev - Navigate to the previous page
  • Next - Navigate to the next page
  • Pages persist for 1 hour (3600 seconds)
  • After REDACT_AFTER_SECONDS, results are automatically redacted
  • Only the user who initiated the search (or the owner) can use pagination buttons

​
Authorization System

JackettSearchBot has a multi-tier authorization system:

​
Authorization Levels

  1. Owner - Defined by OWNER_ID, has full access to all commands
  2. Configured IDs - Listed in AUTHORIZED_CHAT_IDS, permanent access (persists across restarts)
  3. Temporary IDs - Added via /auth, cleared on bot restart

​
Managing Authorization (Owner Only)

/auth
Temporary authorizations (via /auth) are stored in memory only and will be cleared when the bot restarts. For permanent access, add IDs to AUTHORIZED_CHAT_IDS in config.env.

​
Troubleshooting

​
Bot Won’t Start

Error: Missing required config values 
Initialization failed: Missing required config values: TELEGRAM_TOKEN, JACKETT_API_KEY.
Please fill the missing values in config.env and start again.
Solution: Verify all required fields in config.env are filled. Error: database is locked 
Session database is locked. This usually means another bot instance is still running.
Solution: Stop any other running instances or delete stale session files. The bot uses in_memory=True mode to avoid this issue.

​
Authorization Issues

ERROR: NOT AUTHORIZED Solution: Add your Telegram user ID to OWNER_ID or AUTHORIZED_CHAT_IDS in config.env.

​
Search Issues

ERROR: HTTP ERROR OCCURRED Solution: Verify JACKETT_URL is correct and Jackett is running. Check logs at LOG_FILE_PATH for details. RESULT: NO RESULTS Solution: Your query returned no results. Try a different search term or check that your Jackett indexers are configured and working.

​
Next Steps

Commands Reference

Explore all available commands and their advanced usage.

Configuration Guide

Deep dive into all configuration options and customization.

Deployment

Learn how to deploy the bot in production with systemd, Docker, or PM2.

Services

Understand the internal services and extend the bot’s functionality.

Build docs developers (and LLMs) love

Get started for freeTalk to us