Joomla CMS from Source: What the Repository Actually Gives You

What joomla/joomla-cms Is, and What It Is Not

This repository is the source tree for Joomla 5.x. The README says so plainly: "This is the source of Joomla! 5.x." It is not a distribution. The same README states that "Joomla is not installable out of the box from this repository" and points people who want a ready package to downloads.joomla.org for stable builds and to developer.joomla.org for nightly builds. That distinction decides whether this repository is the right thing for you at all.

The audience is developers and integrators: people writing templates, components, plugins or modules, or running a site on a patched tree. Joomla itself is a content management system that the README describes as a web server application requiring PHP plus MySQL, MariaDB or PostgreSQL. The repository is where that application is assembled from PHP sources, Composer dependencies and compiled JavaScript and SASS assets. If you only want to run a website, you are in the wrong place, and the README says as much.

How the Source Tree Turns Into a Running Site

The top-level layout shows the split. administrator/, api/, components/, modules/, plugins/, templates/ and libraries/ hold PHP code. installation/ holds the installer. cli/ is the command line side. build/ and the package.json scripts produce the front-end assets. composer.json and composer.lock pin the PHP dependency graph; package-lock.json pins the Node graph.

package.json carries the identity of the tree: name "joomla", version "5.4.9", license "GPL-2.0-or-later", with engines set to node >=20.0.0 and npm >=10.1.0. Its scripts are the build pipeline. build:js, build:css and build:bs5 each call node build/build.mjs with a different compile flag. install maps to node build/build.mjs --prepare. update chains --copy-assets, --build-pages, --compile-js, --compile-css, --compile-bs and the com_media build. watch and watch:com_media run the same build script in watch mode, which is what you would use while editing template styles.

One mechanism is worth calling out because it is not obvious from the file listing. The README states that Joomla caches the namespaces of its extensions in JOOMLA_ROOT/administrator/cache/autoload_psr4.php, and that when extensions are created, deleted or removed in git, this file must be recreated. Deleting it is enough; the next call to Joomla regenerates it. That is a real operational detail of working from a git checkout rather than a release archive.

Setting Up a Local Environment from the 5.4-dev Branch

The README lists the prerequisites before any command: PHP with the CLI version, Composer for PHP dependencies, Node.js for compiling JavaScript and SASS, and Git. The badge table at the top of the README gives PHP 8.1.0, Node 20.0 and npm 10.1.0. The README points to docs.joomla.org for the detailed local environment instructions.

The first step is cloning and switching to the development branch the README names:

git clone https://github.com/joomla/joomla-cms.git
cd joomla-cms
git checkout 5.4-dev

After the checkout you are on 5.4-dev, which is the default branch of the repository. The next two commands pull the two dependency graphs. Composer handles PHP packages, npm handles the Node packages needed for the asset build:

composer install
npm ci

npm ci installs exactly what package-lock.json pins, which is the behaviour you want on a clean checkout rather than npm install. Once both finish, the PHP dependencies and the build tooling are present. To compile assets for an update rather than a first setup, package.json exposes a single script that runs the whole chain:

npm run update

That script runs --copy-assets, --build-pages, --compile-js, --compile-css, --compile-bs and the com_media build in sequence. If you are editing styles or scripts continuously, npm run watch keeps the build running instead. The README does not document a rollback path for a failed build, so treat a clean checkout as your recovery route.

Where the Source Workflow Breaks Down

The most important limitation is stated by the project itself: this repository does not produce an installable Joomla package out of the box. You need a working PHP environment with a database server before the code is useful, and the README's requirements link covers the full technical requirements rather than the repository repeating them.

The namespace cache is the second failure mode. If you pull a change that adds or removes an extension, and you do not delete administrator/cache/autoload_psr4.php, the README's own note implies you will be running against a stale namespace map. That is a manual step, not something the build scripts handle for you.

Branch targeting is a third trap for contributors. The README's classification table sends bug and patch fixes to 5.4-dev and features or minor changes to 6.2-dev, with a footnote that bugs introduced for the first time in 6.x go to 6.1-dev. Open a pull request against the wrong branch and a maintainer will ask you to retarget it. The recent release list reflects the same split: 5.4.9-rc1 and 6.1.4-rc1 were both tagged on 2026-09-17, and 6.2.0-beta3 on 2026-09-15. Three parallel lines are in flight.

Finally, if you want a site rather than a codebase, none of this is the right tool. The README redirects that audience to the download page, and following the source route means you own the build, the dependency versions and the upgrade path yourself.

Joomla from Source Versus a Packaged CMS

The honest alternative is not another CMS. It is the packaged Joomla release. downloads.joomla.org serves the stable archive, developer.joomla.org serves nightly builds, and both skip Composer, npm and the asset compilation entirely. The difference in approach is who owns the build: with the package, the Joomla project ships you assembled PHP plus compiled assets; with the repository, you assemble them from composer.json, package-lock.json and the build/build.mjs pipeline, and you get the 5.4-dev branch state rather than a tagged release.

A second alternative is a different content management system entirely, and that is a genuine trade-off rather than a like-for-like swap. Joomla's own positioning in the README is a CMS for websites and "powerful online applications", with multilingual websites among the repository topics. Choosing between CMS platforms is a decision about extension ecosystems, hosting requirements and editorial workflow, and nothing in this repository settles it. What the repository does settle is that if you pick Joomla and intend to extend it, you will be working in this tree.

Maintenance, Branches and What GPL-2.0 Means Here

The last push to this repository was on 2026-09-17, and the most recent tags are 6.1.4-rc1 and 5.4.9-rc1, both dated 2026-09-17, with 6.2.0-beta3 on 2026-09-15. The repository is not archived. The version field in package.json reads 5.4.9, matching the 5.4.9 release candidate, so the tree you clone from 5.4-dev tracks that line.

Upgrade cost depends on which line you sit on. Patch and bug fixes land in 5.4-dev. New behaviour, refactoring, performance work and UI changes land in 6.2-dev. Bugs that exist only in 6.x go to 6.1-dev. If you maintain a fork or a long-lived patch set, you are rebasing across three branches, not one, and the README's note about regenerating administrator/cache/autoload_psr4.php applies every time extensions change in git.

Licensing is stated in three places: the README says Joomla is free and open source under the GNU General Public License version 2 or later, LICENSE.txt sits at the top level, and package.json declares "GPL-2.0-or-later". The README links to a licence details page on docs.joomla.org. This is a note about what the repository declares, not legal advice; if you are redistributing a modified tree or bundling it into a product, read the licence text and take your own counsel.

Editorial conclusion

Adopt the source repository if you are building a template, plugin or component and need the 5.4-dev tree under version control; for a production site, take the stable package from downloads.joomla.org instead, because the README states the repository is not installable out of the box. Before you start, confirm your PHP CLI meets the 8.1.0 badge in the README, that Node is at least 20.0.0, and that you have a MySQL, MariaDB or PostgreSQL server available, then clone the 5.4-dev branch and run composer install followed by npm ci. The first thing to verify after setup is that administrator/cache/autoload_psr4.php regenerates correctly, since a stale namespace cache is the failure this project documents itself.

Frequently asked questions

Official sources

1. joomla/joomla-cms on GitHub
2. License: GPL-2.0
3. Project website
4. README
5. Releases