Why is Kirby using 16 character UUIDs?

I just noticed that the new UUID is 16 characters long.

I thought the UUID specification mandates it to be 32 characters?

If you do not follow the specs then it’s just an UID (Unique Identifier), because it’s no longer Universal.

You lose interoperability/compatibility with other systems using proper UUIDs in addition to a drastic increase in the likelihood of collisions.

We had originally planned to use UUID v4 (randomly generated) but then switched to a case-sensitive alphanumerical string. The difference is that UUID v4 uses hexadecimal characters (16 options) while our UUIDs use characters with 62 options. The main advantage is that the string is much shorter, which allows for shorter permalinks.

62^16 is 4.7 * 10^28, which is still a very large number. You are right that it is lower than the number of options of UUID v4. However it is still very much large enough so that the collision probability of 1% is only reached after millions of years creating pages and files. The collision probability scales with the rate of the creation of new entries and realistically even a really large Kirby site will never reach a total number of pages/files that will make a collision likely.

If you prefer to use standardized UUIDs, you can easily replace the built-in generator function:

Uuid::$generator = fn($length) => Str::uuid();

In the same way you can use any other generator function that fits the requirements of your project.

1 Like

Thanks for the detailed explanation, however I have a few concerns:

The name is confusing

UUID means a specific open standard - Universally Unique Identifier. By calling this unique id UUID, you are making a promise that can not be delivered.

In addition, Kirby 3.8 was announced to include UUID, which I - and I assume everyone else - expected to be the actual UUID as described by the open standard, and not a custom scheme that is incompatible with other systems and has higher chance of collision, this means that no one was able to raise possible concerns and no discussion was had before it was implemented.

Is saving 16 characters for permalink really worth dropping an open standard?

At least in my view, permalink is supposed to be ugly, and 16 characters isn’t a big deal. For use cases where it matters (Twitter), there are link shorteners available. It does not seem to be worth the price here.

In addition, the assumption that higher collision chance does not matter for a flat file CMS doesn’t hold true in all cases.


  1. Kirby supports database via virtual pages.

  2. UUID is Universal and is designed to have its records mingle with and move between other compatible systems which also uses UUID.

    So it doesn’t matter if the specific Kirby website doesn’t have many records if the system(s) that it interacts with does.

The second point is especially important, as it empowers Kirby CMS to communicate and exchange data with other systems with minimal friction.

It would not matter if Kirby CMS only wants to run self-contained websites, but with headless mode/API access and virtual pages Kirby clearly has the ambition to be much more, and it would be antithesis to that goal to omit UUID in its core implementation.

Actual UUID scheme not being a built-in option

I am not against having a different, and more ergonomic UID scheme for Kirby, even if it is the default behavior. But I feel the standard UUID scheme should at least be a build-in option, instead of forcing users to have to hack it in, and be responsible for its upkeeping across updates.

1 Like

We openly discussed UUIDs in various threads on Discord while working on the feature and tried to get a good picture of what the community wants. Here are two examples of the discussions …


The PR draft was also out in the public for a pretty long time before the release: UUIDs by distantnative · Pull Request #4506 · getkirby/kirby · GitHub

It’s sometimes difficult for us to tell how we can reach most people with such discussions while actively working on a feature in the open and I’m sorry that you missed it because I think you have some valid points. Discord feels like the best place for this to us, but if you have better ideas, let us know.

Our main decision for the shorter IDs was based on the usability of UUIDs in content. I.e. in textareas + the permalinks. I agree that the permalinks aren’t necessary an issue on their own. But with Kirbytags or Markdown and a significant group of people using Kirby without the Panel, the usability of the UUIDs definitely felt more user-friendly with shorter strings. But this decision also meant that we had to have the generator option for exactly the reasons you mention.

I see your points about the name confusion. This is again based on various reasons.

  1. $page->uid() is already taken. We thought about breaking it, but then decided against it.
  2. The isolated name UUID, as in universally unique identifier is still perfectly describing what the feature does. We had various other options, such as GUID, but decided that this is the most understandable one.
  3. The UUIDs can easily be full-standard UUIDs if you need the longer strings.

I like your idea to support standard UUIDs via an option without having to use a custom plugin for that. I think it would be a good decision to have that + the generator option for maximum flexibility.


We could even add this to the existing content.uuid option:

  • 'alpha-num' (default)
  • 'uuid-v4'
  • false

It really came from the standard UUID, but to be honest we didn’t consider it to be confusing when we switched the format because the meaning of the name itself still works.

1 Like

I totally understand that the literal name of Universally Unique Identifier applies in this case, but because of the mindshare already achieved by UUID the standard it would have been better, in my opinion, to use the term GUID instead.

Of course if we get the built-in option to generate actual UUID-v4 then it would no longer be an issue.

1 Like

To pick up this point and explain my personal experience on this. To be clear: For me it never was an issue so far but my experience could easily lead to similar forum posts once I stumble over an issue I’d be affected of. So I better explain how I follow things around Kirby.

I’m constantly confused where exactly such discussions are happening. There’s the newsletter which I’m always reading as it’s a nice, short summary of all latest things. There’s this forum (to me one of the most permanent/time-immutable places) for discussions, questions, etc. Then there’s Nolt for the roadmap which includes discussions, then there’s github with it’s issues and discussions and there’s Discord which to me still feels like a short-term, non-searchable, real-time medium. I can’t keep up with anything else than semi-regularly scrolling the forum topics and about 2x a year the roadmap. Discord is too short-lived for me, github feels like not relevant for outside of team members.

Hope the experience helps a bit to understand why such forum posts appear.

You are putting the finger deep into a very old wound :rofl: We have the exact same problem as a team.

First there was no forum and email support was a mess. The forum solved this brilliantly.

Then we got more and more feature requests and needed a place for that. We started with a GitHub repo and issues and it again was a nightmare. It took a long time but Nolt solved that part.

With the Kirby Next crowd funding project for Kirby 3 in 2018 we used Slack to chat with our supporters and realized how much better this works for informal chats and discussions. It had a completely different dynamic than the forum. But Slack doesn’t work for bigger communities so we ended up with Discord.

The newsletter has always been a great glue between all of them to summarize what’s happening in the community but of course it is not a medium to stay up to date on a daily basis.

Each tool has its own benefit and it feels like they all attract different parts of the community.

We discussed a lot how we could bring all that closer together. We tried GitHub discussions a while ago and it would indeed bring Nolt and forum posts together and would be better connected to our repo discussions, but it also feels more technical than Discourse.

We just recently tried the new forum channels in Discord but they don’t feel exactly right in there either.

It is really difficult. We keep dreaming about a single platform that could have it all. But that seems like an impossible silver bullet.

If you have ideas or experience with tools that solve this kind of dilemma please let us know