YOURLS

Last reviewed Aug 26, 2026 · 922 words

A URL shortener is 90% domain and 10% software, and YOURLS is the right 10% for one person or one small team. It is a set of PHP scripts that has been in production since 2009, wants 128 MB of RAM and a MySQL database, carries 12,000 stars and an MIT licence, and has an admin page that looks its age. The dated interface is the cost. The payoff is a plugin catalogue and an API that let it do whatever a personal shortener needs without a Bitly subscription, and a redirect that keeps working through a decade of upgrades.

Buy the domain before you touch Docker

A shortener on links.mylongdomain.com shortens nothing, so the first decision is a domain of 4 to 6 characters. Ordinary TLDs like .link or .to run about $10 to $40 a year at last check; the 2-letter vanity ccTLDs that Bitly and Twitter made famous are $100 a year and up, and a few of them belong to countries whose registries have withdrawn domains before. Pick something boring and renewable. Point it at the box that will run YOURLS and only then set up the software, because YOURLS_SITE has to be the exact final URL and changing it later means every existing short link needs a redirect.

Six environment variables and a database

The official yourls image on Docker Hub takes everything from the environment:

services:
  yourls:
    image: yourls:latest
    ports:
      - "8080:80"
    environment:
      YOURLS_SITE: https://sho.rt
      YOURLS_USER: admin
      YOURLS_PASS: change-me
      YOURLS_DB_HOST: yourls-db
      YOURLS_DB_USER: yourls
      YOURLS_DB_PASS: change-me
    depends_on:
      - yourls-db
    restart: unless-stopped
  yourls-db:
    image: mariadb:latest
    environment:
      MARIADB_DATABASE: yourls
      MARIADB_USER: yourls
      MARIADB_PASSWORD: change-me
      MARIADB_ROOT_PASSWORD: change-me-too
    volumes:
      - ./db:/var/lib/mysql
    restart: unless-stopped

Put Caddy in front for TLS, then visit /admin/ once to run the installer, which creates the tables. The bare-metal equivalent is a copy of user/config.php with the same values as PHP constants, and it runs on any host with PHP and MySQL, which is why YOURLS has outlived several generations of fancier shorteners on $3 shared hosting.

Keep public shortening off, forever

YOURLS_PRIVATE defaults to true, meaning only logged-in users can create links, and that is the single most important setting in the product. A short domain that lets anyone create links is a phishing service within the week and on every blocklist within the month. Leave it private. If you want the click stats page for a link to be public while creation stays locked, YOURLS_PRIVATE_INFOS set to false does exactly that. The stats page itself is the nicest trick in YOURLS: append + to any short link, so https://sho.rt/abc+, and you get clicks over time, referrers and countries for that link.

Keywords, plugins and the API

Out of the box keywords are sequential base-36, so your first links are 1, 2, 3. Set YOURLS_URL_CONVERT to 62 before creating anything if you want case-sensitive keywords and a bigger space, because the setting cannot be changed once links exist. Custom keywords are typed in at creation, so sho.rt/cv and sho.rt/talk cost nothing.

Plugins are a folder each under user/plugins/, activated from the admin page, and the ones I would install on day 1 are a random-keyword generator so links stop being guessable, a QR-code plugin so every stats page has a printable code, and one of the bot-filtering plugins so your click counts mean something. Themes for the admin exist too, though the honest advice is that you will spend 30 seconds a week in the admin and it does not matter.

The API is the other reason to pick it over a spreadsheet of links. Every install exposes yourls-api.php. With the signature token from the admin Tools page you can shorten from a shell:

curl -s "https://sho.rt/yourls-api.php?signature=YOUR_TOKEN&action=shorturl&format=json&url=https://example.com/long/path"

That turns YOURLS into a component: a Shortcuts action on a phone, a bookmarklet from the same Tools page, a step in an automation that shortens links before they go into a newsletter. Actions cover expanding, deleting and pulling stats as well, all returning JSON.

Where Shlink beats it and where it doesn't

Shlink is the modern PHP alternative, with a REST API, per-visit tracking, QR codes built in and a separate web client, and it is the better choice if you want a shortener as a product for several people with a polished UI. It also wants more moving parts. YOURLS wins on footprint, on 15 years of upgrade stability, and on being understandable in an afternoon by anyone who has touched PHP. The rest of the field is listed under URL shorteners, and the case for leaving the hosted service at all is in the Bitly alternatives page.

What I'd do

Buy a short domain you will renew for 10 years, run the compose file above behind Caddy, set YOURLS_URL_CONVERT to 62 before the first link, install the random-keyword and QR plugins, and never open public shortening. Back up the single MySQL database nightly; it is the only state. That is a personal shortener with real click stats for the price of a domain, and I would not spend the extra evening on anything heavier unless a team of 5 or more is going to live in the admin.