# Preparing your machine

Before you install Pixelfed, you will need to setup a webserver with the required dependencies:

  • An HTTP server
  • An SQL database server
  • A PHP-FPM server
  • Composer, for PHP dependency management
  • Git, for fetching updates
  • Redis, for in-memory caching and background task queueing
  • GD or ImageMagick, for image processing
  • JPEGOptim, for optimizing JPG
  • OptiPNG, for lossless PNG
  • PNGQuant, for lossy PNG

Shared Hosting

At this stage, it's not possible to install Pixelfed by downloading a ZIP file and uploading the files to your web server. This is because Composer needs to run on the command line.

This doesn't necessarily mean you need a VPS. Some shared hosts give you SSH access, through which you should be able to install Composer and Pixelfed just fine.

# HTTP Web server

The following web servers are officially supported:

  • Apache (with mod_rewrite enabled)
  • nginx

Pixelfed uses HTTPS URIs, so you will need to have HTTPS set up at the perimeter of your network before you proxy requests internally.

# Database

You can choose one of three supported database drivers:

  • MySQL (5.7+)
  • MariaDB (10.2.7+ -- 10.3.5+ recommended)
  • PostgreSQL (10+)

You will need to create a database and grant permission to an SQL user identified by a password. To do this with MySQL or MariaDB, do the following:

sudo mysql -u root -p

You can then create a database and grant privileges to your SQL user. The following SQL commands will create a database named pixelfed and allow it to be managed by a user pixelfed with password strong_password:


create database pixelfed;
grant all privileges on pixelfed.* to 'pixelfed'@'localhost' identified by 'strong_password';
flush privileges;

To do this with PostgreSQL instead, do the following:

sudo -u postgres psql

Once in the psql shell, do the following:


Changing database drivers:

If you decide to change database drivers later, please run a backup first! You can do this with php artisan backup:run --only-db


You can check your currently installed version of PHP-FPM by running php-fpm -v. Make sure you are running PHP >= 7.3.

You can check your currently loaded extensions by running php-fpm -m. Modules are usually enabled by editing your PHP configuration file and uncommenting the appropriate lines under the "Dynamic extensions" section. Make sure the following extensions are installed and loaded:

  • bcmath
  • ctype
  • curl
  • exif
  • iconv
  • intl
  • json
  • mbstring
  • openssl
  • redis
  • tokenizer
  • xml
  • zip

You will also need to enable extensions for image processing drivers:

  • For GD: enable gd
  • For ImageMagick: enable imagick

Additionally, you will need to enable extensions for database drivers:

  • For MySQL or MariaDB: enable pdo_mysql and mysqli
  • For PostgreSQL: enable pdo_pgsql and pgsql

Finally, make sure to set the desired upload limits for your PHP processes. You will want to check the following:

  • post_max_size (default 8M, set this around or slightly greater than your desired post size limit)
  • file_uploads (default On, which it needs to be)
  • upload_max_filesize (default 2M, set this <= post_max_size)
  • max_file_uploads (default 20, but make sure it is >= your desired attachment limit)
  • max_execution_time (default 30, consider raising this to 600 or more so that longer tasks aren't interrupted)

# Creating a dedicated app-user and using UNIX sockets (optional)

For added security, you may want to create a dedicated user specifically for running Pixelfed. To do this:

useradd -rU -s /bin/bash pixelfed

# Configuring PHP-FPM pool and socket


cd /etc/php/php-fpm.d/
cp www.conf pixelfed.conf
$EDITOR pixelfed.conf

Where to define custom PHP-FPM pools

The exact directory you should cd to will vary according to your distribution:

  • Arch Linux uses /etc/php/php-fpm.d
  • Debian and Ubuntu use /etc/php/7.3/fpm/pool.d/ (dependent on PHP version)
  • For other distributions, check your php-fpm.conf to see where exactly you can define *.conf with include=

Make the following changes to the PHP-FPM pool:

;     use the username of the app-user as the pool name, e.g. pixelfed
user = pixelfed
group = pixelfed
;    to use a tcp socket, e.g. if running php-fpm on a different machine than your app:
;    (note that the port 9001 is used, since php-fpm defaults to running on port 9000;)
;    (however, the port can be whatever you want)
; listen =;
;    but it's better to use a socket if you're running locally on the same machine:
listen = /run/php-fpm/pixelfed.sock
listen.owner = http
listen.group = http
listen.mode = 0660

# Configuring Redis socket

Edit redis.conf and edit the following lines:

port 6379                           # change this to "port 0" to disable network packets
unixsocket /run/redis/redis.sock    # 
unixsocketperm 770                  # give permission to "redis" user and group

Where to find redis.conf

The exact location will vary according to your distribution:

  • Arch Linux uses /etc/redis.conf
  • Debian and Ubuntu use /etc/redis/redis.conf
  • For other distributions, check your documentation