YOURLS – Open source link shortening script you can install on your own website

YOURLS – Open source link shortening script you can install on your own website


Organization: YOURLS BV


Version tested: 0.7a (stable)

Date of this version release: 21-Mar-2011

Based on PHP using MySQL backend for data storage.

Licensing model: GNU LGPL v3 License  or commercial license available at

This article describes how to install YOURLS on your own web server, including configuration options and the ability to create custom plugins or themes for YOURLS! The first part of this tutorial will show you how to set up YOURLS on a Debian Lenny VPS with Apache2 as the webserver. After following this tutorial you are good to go, so if you have some experience with command-line usage of Linux/Unix, Apache and MySQL you are ready to go!

If you're not sure if your host meets the requirements please first consult their documentation.


Apache 1.3 or newer (tested with 1.3, 2.2) PHP 5.2+ (tested with 5.2, 5.3)  MySQL 4+ (tested with 5.0, 5.1) mod_rewrite Apache module enabled for .htaccess usage A recent version of cURL installed on your server Your own domain name / subdomain pointing to your webhosting account that is publically accessible Your installation will be publicly available at

This installation uses MySQL, so if you are new to MySQL please have a look at this article before proceeding with the tutorial. It should be sufficient for most users.

If you do not want to use MySQL (or cannot) another option is using flat files instead of MySQL. This might be useful for people behind very restrictive firewalls or who don't need the features offered by open source databases like MySQL/MariaDB/PostgreSQL. However this needs some technical skill and makes your website less flexible (e.g., no user registration).


As already stated in the requirements section, make sure that Apache2/mod_rewrite is installed on your machine, Apache has write access to the /yours directory and that you have MySQL installed with PHP support. If you are unsure, ask your host to check it for you.

Start with creating the MySQL user and database for YOURLS.

CREATE USER 'yours'@'localhost' IDENTIFIED BY 'password'; CREATE DATABASE IF NOT EXISTS `yours` DEFAULT CHARACTER SET utf8 COLLATE utf8_general_ci; GRANT ALL ON yours.* TO 'yours'@'localhost'; FLUSH PRIVILEGES;

MySQL will not allow you to create a database called "yours" so please enter another name instead, e.g. "mystuff". Make sure to pick something other than your username as well! If you want to use another database server like PostgreSQL or MariaDB check out the official documentation on how to do this. 

Now let's download the source of YOURLS and extract it in your /yours directory (make sure you already created it) using the following commands:

cd /yours mkdir yours-temp wget unzip mv YOURLS-master yours rm -rf YOURLS-master

This will create a "yours" directory where we'll be doing all our work from now on, so please cd into it:

cd yours

Using cURL is recommended for installing and updating the software because in some cases alternatives like WGET cannot show you any output in case something goes wrong. If you are using Windows please install cURL for your own system.

If you already have an old version of YOURLS installed, then the following command will remove everything that is not needed anymore:

rm -rf yours/*

Now it's time to configure YOURLS! First of all, open the config.php file in your editor and enter a secret authorization code (between 5 and 20 characters). You can also leave this empty if you don't want to use login protection but I highly recommend setting one up! This makes it possible for users not to think twice about entering their password when they visit your website again ;)

If you go with the default values suggested by the config generator make sure to set $authorization_method to "login" or leave it empty if you don't use login protection!

Next open the database.php file and enter your MySQL details as you should have created them before. YOURLS should support every database, but please check out the official documentation for more information about all the possible options.

If everything is fine so far, save both files again and go to or just start with an update by  entering "update2" into the URL instead of "new". This will generate a new configuration file which include all existing settings from your current YOURLS installation. Check if everything is correct before you proceed any further! When upgrading an old version of YOURLS make sure to enter "update2" into the URL!

After that is done go to for the first run of YOURLS where you'll be asked some simple questions about your website. Provide all necessary information and make sure to read what you are doing before pressing any buttons or checking any checkboxes. If everything looks fine, agree to the default settings by clicking on OK, otherwise just click Cancel. Your old version will stay intact if anything goes wrong because this installer script will not overwrite existing files but rather  create new ones within your current installation folder named "backup_yyyy-mm-dd-hh-mm".

Now open config.php in a text editor again and enter an Admin Username and Password for your website. Also check if the $uncompressed_mjpeg value is set to 1 and if so change it to 0 ;) Now you can download and install a free plugin for WordPress called "YOURLS Shortlinks" or any other CMS you are using, or just add two lines of HTML code into every web page where you want YOURLS links to show up.

Please note than when updating existing websites from older versions of YOURLS, these settings will be overwritten after the update process! If you want to keep your previous options make sure to back them up before starting the installation proccess again! Backup files should be located in /yours/backup_yyyy-mm-dd-hh-mm.


This should have given you a brief intro on how to install YOURLS on your own server. If you need more information, then please head over to the official documentation which has lots of useful information about installing, configuring and using YOURLS! Also feel free to leave your thoughts in the comments below :)

If you would like to proceed with the installation, then please download this file into your website's public html folder. As soon as you start it (make sure that .htaccess is enabled) YOURLS will install itself and ask you a few questions about your website right away...


We are social