How to Install and Configure YOURLS on Your Server

What is YOURLS and Why Create Your Own URL Shortener?

YOURLS (Your Own URL Shortener) is an open-source PHP script that enables you to run your own URL shortening service. According to recent industry data, over 50 billion shortened URLs are created annually across all platforms, making custom URL shortening a valuable tool for businesses and individuals alike. With self-hosted solutions like YOURLS, you gain complete control over your links, branding, and data.

Creating your own URL shortener offers several compelling advantages: full ownership of your data, custom branded domain names, detailed analytics, no third-party limitations, and the ability to customize features to your specific needs.

Prerequisites for Installing YOURLS

Before installing YOURLS, ensure your hosting environment meets these minimum requirements:

• Web Server: Apache, Nginx, or LiteSpeed
• PHP Version: PHP 5.6 or higher (PHP 7.4+ recommended)
• Database: MySQL 5.0+ or MariaDB
• PHP Extensions: json, mysql (or mysqli/pdo), curl, mbstring
• Storage: Minimum 50MB disk space

Most modern hosting solutions easily support these requirements, and many providers offer one-click installations for popular PHP applications.

Step-by-Step YOURLS Installation Guide

Step 1: Download YOURLS

Visit the official YOURLS repository or website to download the latest stable version. Extract the files to your local machine. The package includes core PHP files, sample configuration files, and admin interface components.

Step 2: Create the Database

Log into your hosting control panel (cPanel, Plesk, or similar) and create a new MySQL database. Note the database name, username, and password—you'll need these for configuration. Most support documentation provides detailed instructions for database creation.

Step 3: Configure YOURLS

Rename the user/config-sample.php file to user/config.php. Open this file in a text editor and configure the following settings:

define( 'YOURLS_DB_USER', 'your_database_username' );
define( 'YOURLS_DB_PASS', 'your_database_password' );
define( 'YOURLS_DB_NAME', 'your_database_name' );
define( 'YOURLS_DB_HOST', 'localhost' );
define( 'YOURLS_DB_PREFIX', 'yourls_' );

define( 'YOURLS_SITE', 'https://your-domain.com' );
define( 'YOURLS_HOURS_OFFSET', 0 );
define( 'YOURLS_LANG', '' );

define( 'YOURLS_UNIQUE_URLS', true );
define( 'YOURLS_PRIVATE', true );

$yourls_user_passwords = array(
    'admin' => 'your_secure_password',
);

Step 4: Upload Files

Upload all YOURLS files to your web server using FTP or the file manager in your hosting control panel. Place the files in the root directory or a subdirectory where you want your short URLs to resolve. Ensure proper file permissions are set (typically 755 for directories, 644 for files).

Step 5: Complete Installation

Navigate to your YOURLS installation URL in a web browser. Add /admin/install.php to your site URL (e.g., https://example.com/admin/install.php). Follow the on-screen instructions to create the necessary database tables. Upon completion, you'll receive a confirmation message.

Step 6: Secure Your Installation

After installation, implement these security measures: change the default admin username and password, enable HTTPS on your domain, consider restricting admin access by IP address, and regularly update YOURLS to the latest version. Review the system policies for additional security recommendations.

Key Features of YOURLS

YOURLS offers a comprehensive feature set that rivals commercial alternatives:

Feature	Description
Custom Short URLs	Generate memorable, branded short links using custom keywords
API Access	Full REST API for programmatic link creation and management
Statistics Dashboard	Track clicks, referrers, and geographic data in real-time
Plugin System	Extend functionality with numerous available plugins
Bookmarks	Browser bookmarklets for quick link shortening
QR Codes	Generate QR codes for any shortened URL

YOURLS vs. Other URL Shortening Solutions

When evaluating URL shortening options, consider the following comparison:

td>Data Ownership

Aspect	YOURLS (Self-Hosted)	Bitly	TinyURL
Cost	Free (hosting costs)	Free/Premium	Free
Branding	Fully custom domain	Custom (premium)	Limited
Complete control	Third-party	Third-party
Analytics	Detailed, private	Comprehensive	Basic
Setup Complexity	Medium	Easy	Easy

According to marketing studies, branded short URLs can increase click-through rates by up to 39% compared to generic alternatives, making self-hosted solutions particularly valuable for businesses.

Advanced Configuration and Optimization

Using Custom Domains

To use multiple domains with YOURLS, configure your DNS settings to point additional domains to your server. Add these domains in the YOURLS configuration under the YOURLS_SITE definition, and configure your web server to handle requests for all domains.

Enabling Pretty Permalinks

For cleaner URLs (e.g., example.com/abc123 instead of example.com/?id=abc123), configure your web server's rewrite rules. For Apache, ensure mod_rewrite is enabled and add the appropriate rules to your .htaccess file.

Performance Optimization

Implement caching mechanisms to improve response times. Enable PHP opcache, utilize a content delivery network (CDN) for static assets, and consider implementing database query caching. Regular maintenance, including database optimization, helps maintain optimal performance.

Common Use Cases for Your Own URL Shortener

Self-hosted URL shorteners serve various purposes across different contexts:

1. Marketing Campaigns: Track the effectiveness of marketing initiatives with branded, memorable links
2. Social Media: Create concise links for Twitter, Instagram, and other platforms with character limitations
3. Affiliate Tracking: Monitor affiliate links and manage redirects
4. Internal Communications: Simplify sharing long internal URLs within organizations
5. E-commerce: Create memorable product links for advertising and promotions

Troubleshooting Common Issues

Database Connection Errors

If YOURLS cannot connect to the database, verify your credentials in config.php, ensure the database user has appropriate permissions, and confirm the database server is running. Check your hosting provider's system status page for any ongoing issues.

404 Errors on Short Links

If shortened URLs return 404 errors, verify your web server's rewrite rules are configured correctly. For Nginx servers, ensure the appropriate location blocks are added to your server configuration.

Plugin Conflicts

When experiencing unexpected behavior, deactivate all plugins and re-enable them sequentially to identify conflicts. Ensure all plugins are compatible with your YOURLS version.

Conclusion

Creating your own URL shortening service with YOURLS provides unmatched control over your links, complete data ownership, and professional-grade features without recurring subscription costs. The installation process is straightforward, and the platform offers extensive customization options through its plugin system and API.

Whether you're a marketer seeking branded links, a developer building link management tools, or an organization requiring private link tracking, YOURLS delivers a robust, scalable solution. With proper configuration and maintenance, your self-hosted URL shortener can handle millions of links while providing valuable insights into your audience's behavior.

Ready to get started? Explore our documentation for additional resources, or contact our team for hosting solutions optimized for YOURLS installations.