Installation

Install JackettSearchBot and set up your development environment

Prerequisites

Before installing JackettSearchBot, ensure you have the following:

• Python 3.10 or higher - The bot requires Python 3.10+
• uv package manager - Fast Python package installer and resolver
• Telegram Bot Token - Obtain from @BotFather
• Jackett Instance - Running and accessible from your machine

The bot uses tgcrypto for better performance, which is automatically installed on Python 3.10-3.12. On Python 3.13+, it requires C++ build tools or will be skipped.

Installing uv

The project uses uv for fast and reliable dependency management. Install it using one of these methods:

macOS/Linux

curl -LsSf https://astral.sh/uv/install.sh | sh

For more installation options, visit the official uv documentation.

Installation Steps

1. Clone the repository

   Clone the JackettSearchBot repository to your local machine:

   git clone <your-repo-url>
   cd JackettSearchBot
   
2. Install dependencies

   Use uv to create a virtual environment and install all dependencies:

   uv sync
   

   This command will:

   • Create a local .venv directory automatically
   • Install all required dependencies from pyproject.toml
   • Lock versions in uv.lock for reproducible builds

   You don’t need to manually activate the virtual environment when using uv run. The tool handles this automatically.

3. Verify installation

   Check that the installation was successful:

   uv run python -c "import jackett_bot; print('Installation successful!')"
   

Dependencies

The bot requires the following Python packages (automatically installed by uv sync):

• pyrogram - Telegram MTProto API framework
• python-dotenv - Environment variable management
• httpx - Modern HTTP client for API requests
• tgcrypto - Encryption library for better performance (Python < 3.13)

All dependencies are defined in pyproject.toml and managed by uv.

Project Structure

After installation, your project directory will look like this:

JackettSearchBot/
├── .venv/                      # Virtual environment (created by uv)
├── jackett_bot/               # Main bot package
│   ├── app.py                 # Bot application and setup
│   ├── config.py              # Configuration management
│   ├── handlers/              # Command handlers
│   └── services/              # Business logic services
├── main.py                    # Application entry point
├── config.env.example         # Configuration template
├── pyproject.toml             # Project metadata and dependencies
├── requirements.txt           # Alternative dependency list
└── uv.lock                    # Locked dependency versions

Alternative Installation with pip

If you prefer using pip instead of uv:

# Create virtual environment
python -m venv .venv

# Activate virtual environment
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

Using pip may result in different dependency versions than those tested with uv. For the most reliable experience, use uv as recommended.

Next Steps

Now that you’ve installed JackettSearchBot, proceed to:

• Configuration - Set up your environment variables
• Running the Bot - Start and manage the bot