README.md

PBModular

A lightweight and flexible modular bot framework on Pyrogram.

PBModular is a lightweight and flexible bot framework designed to be something between a userbot and a traditional bot, giving you the power to automate tasks and extend functionality with ease.

---

Table of Contents

• Key Features
• Getting Started
  • Prerequisites
  • Quick Installation
  • Manual Installation
• Running as a Systemd Service
• Documentation
• Contributing
• Contributors
• License

---

Key Features

• Modular Design: Easily extend and customize your bot's features with a plugin-based architecture. Explore official modules.
• Cross-Platform: Supports Linux, Windows, and Android (Termux).
• Open Source: Contribute, modify, and adapt the bot to your specific needs under the GPLv3 license.

Note for Windows and Android: Remove the uvloop dependency from requirements.txt before installation, as it is not supported on these platforms.

Getting Started

Prerequisites

Make sure you have the following software installed on your system:

• Python (version 3.11 or newer)
• Git

Quick Installation (Linux/Windows)

We provide convenient installation scripts for Linux and Windows:

Linux (Bash):

sh -c "$(curl -fsSL https://raw.githubusercontent.com/PBModular/bot/refs/heads/master/install.sh)"

Windows (PowerShell):

iex ((New-Object System.Net.WebClient).DownloadString('https://raw.githubusercontent.com/PBModular/bot/refs/heads/master/install.ps1'))

Manual Installation

1. Clone the repository:

   git clone https://github.com/PBModular/bot PBModular
   cd PBModular

2. Create and activate a virtual environment (recommended):

   # For Linux/macOS
   python3 -m venv venv
   source venv/bin/activate
   
   # For Windows
   python -m venv venv
   .\venv\Scripts\activate

3. Install dependencies:

   pip install -r requirements.txt

4. Configure your bot:

   # Create the config file from the example
   cp config.example.yaml config.yaml
   
   # Edit the configuration file with your favorite editor
   nano config.yaml 

5. Run the bot:

   python main.py

Running as a Systemd Service (Linux)

Use this example systemd service file to run your bot automatically at system boot. Create a file like /etc/systemd/system/pbmodular.service:

[Unit]
Description=PBModular Bot
After=network.target

[Service]
WorkingDirectory=/path/to/bot/sources
Type=simple
User=your_user
# If not using a venv, change this path to your system's python executable
ExecStart=/path/to/bot/sources/venv/bin/python3 -u /path/to/bot/sources/main.py
# Restart bot after fail
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

Remember to replace /path/to/bot/sources and your_user. Then, enable and start the service:

sudo systemctl enable --now pbmodular.service

Documentation

Full documentation, including module development guides, is available on our wiki:

• English: https://pbmodular.github.io/wiki/
• Russian: https://pbmodular.github.io/wiki/ru/

Contributing

We welcome contributions! Feel free to open issues, submit pull requests, or join the discussion. A good place to start is our community chat.

• Bug Reports & Feature Requests: Create an issue
• Community Chat: Join us on Telegram

Want to contribute documentation in your language? Contact @SanyaPilot or @Ultra119.

Contributors

A big thanks to everyone who has contributed to PBModular!

SanyaPilot 💻 💡 📖

Ultra119 🚧 💻 📖

CakesTwix 🌍

vilander1337 📖 💻

License

This project is licensed under the GNU General Public License v3.0. See the LICENSE file for details.