Skip to main content

​
Requirements

MadelineProto has specific system and PHP requirements to ensure optimal performance and compatibility.

​
PHP Version

PHP 8.2 or higher is required. MadelineProto will not work with PHP 8.1 or earlier versions.

​
64-bit Required

MadelineProto requires a 64-bit version of PHP. Check your PHP version and architecture: 
php -v
php -r "echo PHP_INT_SIZE * 8 . ' bit PHP';"
Expected output: 
PHP 8.2.4 (cli) (built: Mar 16 2024 08:40:08) (NTS)
64 bit PHP
If you see “32 bit PHP”, you must install the 64-bit version. MadelineProto will not function correctly on 32-bit PHP.

​
Required PHP Extensions

The following PHP extensions are required for MadelineProto to function:
1

Core Extensions

These extensions are mandatory:
  • mbstring - Multibyte string handling
  • xml - XML parsing
  • json - JSON encoding/decoding
  • fileinfo - File type detection
  • dom - DOM manipulation
  • filter - Data filtering
  • hash - Hashing functions
  • zlib - Compression support

​
Verify Installed Extensions

Check which extensions are installed: 
php -m
Or check specific extensions: 
php -r "echo extension_loaded('mbstring') ? 'mbstring: OK' : 'mbstring: MISSING';"
php -r "echo extension_loaded('xml') ? 'xml: OK' : 'xml: MISSING';"
php -r "echo extension_loaded('json') ? 'json: OK' : 'json: MISSING';"

​
Install Missing Extensions

sudo apt update
sudo apt install php8.2-mbstring php8.2-xml php8.2-json \
                 php8.2-fileinfo php8.2-dom php8.2-curl \
                 php8.2-zip php8.2-gmp php8.2-bcmath
These extensions are optional but highly recommended for better performance:

gmp

Highly RecommendedSpeeds up authorization and cryptographic operations significantly.
sudo apt install php8.2-gmp

openssl

Highly RecommendedProvides faster cryptographic operations.
sudo apt install php8.2-openssl

uv

Performance BoostGreatly speeds up MadelineProto by providing an efficient event loop.
pecl install uv

primemodule + FFI

Maximum PerformanceProvides the fastest possible cryptographic operations.See prime.madelineproto.xyz

​
Database Extensions (Optional)

For using external databases to reduce RAM usage:
  • pdo - PDO database abstraction
  • pdo_mysql - MySQL support
  • pdo_pgsql - PostgreSQL support
  • redis - Redis support
# MySQL
sudo apt install php8.2-mysql

# PostgreSQL  
sudo apt install php8.2-pgsql

# Redis
sudo pecl install redis

​
Math Extensions (Optional)

Either gmp OR bcmath is recommended: 
# GMP (preferred)
sudo apt install php8.2-gmp

# OR BCMath (slower alternative)
sudo apt install php8.2-bcmath

​
Composer

For installing via Composer (recommended), you need Composer 2.0+: 
# Check Composer version
composer --version

# Install Composer
curl -sS https://getcomposer.org/installer | php
sudo mv composer.phar /usr/local/bin/composer

​
System Requirements

​
Memory

  • Minimum: 128 MB RAM
  • Recommended: 256 MB+ RAM
  • With Database: Can run with as low as 64 MB when using MySQL/PostgreSQL/Redis
Memory usage depends on your bot’s workload. For bots in many groups, consider using a database backend to reduce RAM usage.

​
Disk Space

  • Minimum: 50 MB free space
  • Recommended: 200 MB+ for session files and temporary data

​
Network

  • Stable internet connection
  • Ability to connect to Telegram servers (ports 80, 443)
  • For MTProxy: Additional port access may be needed

​
Platform Support

Fully Supported
  • Ubuntu 20.04+
  • Debian 10+
  • CentOS 8+
  • Alpine Linux
  • Any Linux distribution with PHP 8.2+
Recommended for production deployments.

​
Conflicting Packages

The following packages must not be installed as they conflict with MadelineProto:
  • ext-pthreads - Conflicts with async operations
  • krakjoe/pthreads-polyfill - Not compatible
If you have these installed, remove them: 
composer remove krakjoe/pthreads-polyfill

​
Verification Script

Run this script to check if your system meets all requirements: 
<?php

echo "=== MadelineProto Requirements Check ===\n\n";

// PHP Version
echo "PHP Version: " . PHP_VERSION;
if (version_compare(PHP_VERSION, '8.2.0', '>=')) {
    echo " ✓\n";
} else {
    echo " ✗ (8.2+ required)\n";
}

// 64-bit
echo "Architecture: " . (PHP_INT_SIZE * 8) . "-bit";
if (PHP_INT_SIZE === 8) {
    echo " ✓\n";
} else {
    echo " ✗ (64-bit required)\n";
}

// Required extensions
echo "\nRequired Extensions:\n";
$required = ['mbstring', 'xml', 'json', 'fileinfo', 'dom', 'filter', 'hash', 'zlib'];
foreach ($required as $ext) {
    echo "  $ext: " . (extension_loaded($ext) ? '✓' : '✗') . "\n";
}

// Recommended extensions  
echo "\nRecommended Extensions:\n";
$recommended = ['gmp', 'openssl', 'uv', 'bcmath', 'ffi'];
foreach ($recommended as $ext) {
    echo "  $ext: " . (extension_loaded($ext) ? '✓' : '(not installed)') . "\n";
}

// Database extensions
echo "\nDatabase Extensions (optional):\n";
$database = ['pdo', 'pdo_mysql', 'pdo_pgsql', 'redis'];
foreach ($database as $ext) {
    echo "  $ext: " . (extension_loaded($ext) ? '✓' : '(not installed)') . "\n";
}

echo "\n=== End of Check ===\n";
Save as check.php and run: 
php check.php

​
Next Steps

Once your system meets the requirements:

Installation

Install MadelineProto via Composer or PHAR

Quick Start

Build your first bot in minutes

​
Troubleshooting

MadelineProto requires 64-bit PHP. Download and install the 64-bit version:
After installing extensions, restart your web server or PHP-FPM:
# Apache
sudo systemctl restart apache2

# Nginx + PHP-FPM  
sudo systemctl restart php8.2-fpm

# Verify extension loaded
php -m | grep mbstring
If you can’t install GMP or BCMath, MadelineProto will still work but slower.For best performance, use Docker image which includes all optimizations:
docker pull hub.madelineproto.xyz/danog/madelineproto:latest
Performance Tip: For maximum performance, install the primemodule extension. See prime.madelineproto.xyz for installation instructions.

Build docs developers (and LLMs) love

Get started for freeTalk to us