Install YOURLS URL Shortener

What is URL Shortening? A way to truncate long URL addresses so they are shorter in length. Why would one shorten a URL? They are easier to share! Twitter for example, has a 140-character limit on messages. Shorter URLs mean you can add more text to your tweet.

There are many URL shortening services available, such as bit.ly, ow.ly, is.gd, and Awe.sm. Each has its own take on URL shortening and works adequately. I was looking for specific features in a URL shortener.

1. Self-hosted – Shortening services are a dime a dozen, who knows how long they will last. For example the short lived bieber.ly was up for less than a week. I want to be able to access the archive of URLs I have shortened and shared.

2. Personalized – When I share links I want them to be part of my “personal brand.”

3. Analytics – I want to see the reach of the links I share. Click count, referrer location, and geographical statistics.

4. Client integration – Currently I use TweetDeck on both my desktop and laptop. On my iPhone I use the native Twitter client. I want links I share from any of my devices to come from the same service.

5. WordPress integration – After I publish a blog post the last thing I want to do is more work. A service that will automate link shortening and sharing is key.

6. Free – Self explanatory

YOURLS really meets my every need. It is loaded with features such as:

1. Sequential or custom shortened links.
2. Bookmarklets that make it simple to shorten links right from your browser.
3. Analytics that include historical reports, referrer tracking, and visitor location.
4. Simple and clean AJAX interface.
5. WordPress integration.
6. API which allows for Twitter client integration (Specifically TweetDeck and Twitter for iPhone).
7. Easy to install.

I have been using YOURLS for about 10 months now and love it. In those 10 months, I have shared 96 links and had 3,296 clicks. There is some room for improvement, especially with the analytics. The YOURLS road map states a plan for Google Analytics support, but unfortunately there is no ETA.

Before you get started, you will need a domain name and a web host. I run my YOURLS setup off my HostGator account and purchased my domain with NameCheap. Since Twitter limits tweets to 140 characters, it is best to use a short domain name for your YOURLS installation. If you need assistance coming up with a short domain name try the free search tool domai.nr.

If you are not using HostGator, make sure your webserver meets the following requirements:

1. mod_rewrite enabled
2. at least PHP 4.3
3. at least MySQL 4.1

Pre-Install Notes:

*WordPress and YOURLS cannot be installed in the same directory. For example, if your blog is www.blogblog.com your YOURLS installation will need to be something like www.blogblog.com/yourls.
*For the purpose of this tutorial I will be installing YOURLS to www.zachgeek.com/y/. This means any links I shorten will look like www.zachgeek.com/y/abc/.
*I will also discuss how to remove the www. so your shortened URL will be 4 characters shorter.
*Finally I will be assuming you are using HostGator or similar web host with cPanel access.

Install & Configure YOURLS

Step 1: Download and Unzip YOURLS
Download here. Once the download has finished, unzip the files to your local machine.

Step 2: Setup MySQL database and user
Log into your cPanel. The address is normally http://www.yourdomain.com/cpanel/.


Click MySQL Databases

Enter MySQL Database Name

Create MySQL User

Grant User All Privleges

MySQL Database Setup Complete


Step 3: Modify YOURLS configuration file
Browse to where you downloaded YOURLS in Step 1. Open the includes folder and rename config-sample.php to config.php. Now let’s open the config.php and make the changes. I am attaching a screenshot of my config.php and the changes I made to coincide with the database I created above. I have removed some of the developer’s comments and replaced them with my own to help explain some of the options. Other parts are self explanatory. The file you downloaded will look a little different.


Step 4: Upload files
Upload the files to your web host. For example, I will be uploading my files to /home/zachgeek/public_html/y/

Step 5: Install and setup database
Browse to your new installation.
ie: http://www.ex.com/directory/admin/

Click Install

Installation Complete

Step 6: Remove www. from shortened links (optional, but recommended)
You can force your webserver to remove www. from your shortened links. This will save 4 characters on your links and it is really easy to do. You can download my .htaccess file here. Make sure you modify it for your domain and directory. Then upload it to your YOURLS directory.

Once you do this your shortened links will look like this: zachgeek.com/y/abc1 instead of www.zachgeek.com/y/abc1.

Note: If you are not installing YOURLS to a subdirectory, your .htaccess file will be different. You can find the instructions here.

I hope this How To helps you create your own URL shortening service! Please feel free to leave questions and comments below and I will try my best to assist.

Comments (21):

  1. jbrewlet

    September 3, 2012 at 2:24 am

    Great article. I also have bought domains from Namecheap and have the original hosted on Fatcow. I have transferred the nameservers of the original to Fatcow previously.

    Yourls is installed in a subdirectory and I’ve setup the config.php file, added the database etc. I can get into the admin page by setting the site url in config.php to the original url but not the vanity.

    I cannot figure out whether I need to transfer the nameservers of the vanity domain or just setup the DNS in another way. I have tried to URL Redirect and set the A Address but these do not work.

    If that made any sense I would love your input. There doesn’t seem to be much help or documentation with the DNS setup/nameservers part. How is your nameserver configured for the vanity?


    • Zach Matthai

      September 3, 2012 at 9:16 pm

      Sounds like you need to ask Fatcow if they allow for addon domains. It sounds like that is where the confusion may be. Addon domains act as “sub accounts” to your main hosting account. If they do not you may want to investigate providers that do. Addon domains are a common feature for most hosting packages.

      Feel free to drop me an e-mail if you need further help.

  2. Lenny

    September 8, 2012 at 9:40 am

    Thanks for the post! Have you used this plugin? http://blog.yourls.org/2011/03

    I added the header using another plugin as example, it installs fine but couldn’t get it to do what it claims. My other guess is that it could be that the path are not declared appropriately but I have tried gazillion iterations. I’m no php guru so it might be a simple mistake.

    Just curious if the same happened to you.


    • Zach Matthai

      September 12, 2012 at 1:23 am

      I have not had a chance to try that plugin.

  3. Alex

    October 27, 2012 at 6:42 am

    great tut thx. I am planning to install it. I have 10 domain names hosted on the same server. Does Yourls work for multiple domain names ?

    • Zach Matthai

      August 4, 2011 at 3:33 pm

      Alex, I am not 100% sure but I think you would need to install an instance for each domain. Unless you had 9 domains doing a redirect on the remaining domain.

  4. Luis

    November 10, 2012 at 1:33 am

    Man Thank you!! I installed this and I’m loving it! 🙂 cheers!

  5. Sneuga39

    January 3, 2013 at 5:37 am

    Why my installation result is:
    File .htaccess sucesfully created/updated
    Table ‘yourls_url’ not crated
    Table ‘yourls_option’ not crated
    Table ‘yourls_log’ not crated
    YOURLS tables not sucessfully created.

    • Zach Matthai

      January 5, 2013 at 4:11 pm

      Sounds like the MySQL settings in config.php are not correct. Have you double checked the username/password?

  6. leon

    September 24, 2013 at 6:03 am

    cheers fella, great article—worked first time.

  7. Dave J Dages

    November 13, 2013 at 9:57 am

    Thanks for the tutorial. Is there any conceivable way that I could have my “domain.com” route to a public page, with domain.com/short for the redirects, without the extra complication? I want to have wordpress under my domain, but it doesn’t have to be right there.

    • Zach Matthai

      December 9, 2013 at 9:05 am

      Yes. Just create a folder /short to upload the files for YOURLS. Sorry for the delay in replying. If you need additional help hit up my contact page.

  8. James

    December 2, 2013 at 4:03 pm

    I’ve got most of this done right, I think, but I’m struggling to get the admin panel to come up. In config.php, I have it set to my main URL, not the short one that I want to use for shortlinks. The short URL doesn’t have hosting attached.

    Do I install the files to the main URL or to my short URL? I can add hosting to the short one if I must.

    I’m also wrangling with WordPress, and GoDaddy. I uploaded the files to a new subdirectory of webroot called Yourls.

    • Zach Matthai

      December 9, 2013 at 9:06 pm

      James – You need to install the files to the short URL. So you will need additional hosting :\ If you have more questions contact me via e-mail. 🙂

  9. shahzaib

    January 16, 2014 at 9:55 am

    does it works with free hosting site like 000webhost and free free domain i.e: .tk
    pls help

    • Zach Matthai

      January 17, 2014 at 1:35 pm

      The host will need to support:

      1. mod_rewrite enabled
      2. at least PHP 4.3
      3. at least MySQL 4.1

      As long as you have full control over the domain I do not see why not.

    • Simeon Prince

      October 5, 2014 at 2:20 pm

      please don’t use .tk. it’s a scam, as i used it before on more than 1 occasion. when your website gets popular, you’ll find that the domain is stolen by the same .tk guys. i wanted to cry when that happened to me twice. anyway, i wised up and bought my own domain names and hosting. 000webhost is good to start with for free hosting, but still get your own domain name. it’ll save you some grief. also, 000webhost regularly goes down. so, use it only as an alternative until you pay for pro web hosting.

      • Zach Matthai

        October 21, 2014 at 9:44 pm

        Thanks for sharing your experience with those two providers. A reputable low cost company to purchase domains from is http://www.namecheap.com. I have used them for years now without issue.

        • Simeon Prince

          October 22, 2014 at 7:53 am

          I use namecheap too. They’re my only web host now. anytime i have problems, I always get help from them on twitter. @namecheap


Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.