Link Search Menu Expand Document


MadelineProto requires the mbstring, xml, json, fileinfo, gmp, openssl, iconv, gd extensions to function properly.

The ffi and uv extensions and the PrimeModule and nghttp2 libraries are also highly recommended to improve performance.

PHP 8.2+ is required.

MadelineProto explicitly supports Linux and UNIX systems (including Mac OS).
I don’t recommend using Windows: MadelineProto generally works on Windows, though there might be some random issues caused by AV engines, so I personally recommend using Linux.

Mac OS+Docker note: If you encounter issues running MadelineProto on Docker on Mac OS, make sure to enable ephemeral filesystem support with a database as described here », and change the session path in bot.php to point to a unique path in /tmp, not in a mounted volume.

Running on webservers and webhosts is fully supported, but I highly recommend running long-running applications like event handler bots via CLI.

Running via docker is highly recommended, see here » for more info on how to run MadelineProto in docker, on any Linux distro.

Otherwise, see here » for more info on how to install MadelineProto dependencies manually on Ubuntu.

Follow these instructions » to install MadelineProto dependencies on any linux distro, using the official docker image.


To install MadelineProto dependencies manually on Ubuntu, run the following command in your command line:

sudo apt-get update
sudo apt-get install software-properties-common -y
sudo LC_ALL=C.UTF-8 add-apt-repository -y ppa:ondrej/php
sudo apt-get update
sudo apt-get install php8.2 php8.2-dev php8.2-xml php8.2-zip php8.2-gmp php8.2-cli php8.2-mbstring php8.2-ffi php8.2-iconv php-pear libuv1-dev nghttp2 -y
sudo pecl install uv-beta
echo | sudo tee $(php --ini | sed '/additional .ini/!d;s/.*: //g')/uv.ini
echo ffi.enable=1 | sudo tee $(php --ini | sed '/additional .ini/!d;s/.*: //g')/ffi.ini

echo 262144 | sudo tee /proc/sys/vm/max_map_count
echo vm.max_map_count=262144 | sudo tee /etc/sysctl.d/40-madelineproto.conf

sudo mkdir -p /etc/security/limits.d/

echo '* soft nofile 1048576' | sudo tee -a /etc/security/limits.d/40-madelineproto.conf
echo '* hard nofile 1048576' | sudo tee -a /etc/security/limits.d/40-madelineproto.conf

cd /tmp
sudo apt-get install build-essential
git clone
cd PrimeModule-ext && make -j$(nproc) && sudo make install

The max_map_count sysctl configuration is required to avoid “Fiber stack allocate failed” and “Fiber stack protect failed” errors, since the PHP engine mmaps two memory regions per fiber, and the soft/hard nofile limits increase the maximum open FD limit, to allow opening many TCP sockets for improved upload and download performance, and to avoid errors.

Next section