choosealicense.com: How GitHub's License Guidance Site Works and How to Run It Locally

What choosealicense.com Does and Who Maintains It

choosealicense.com is a website that helps developers choose an open source license for a new project. It presents a small number of popular licenses with plain-language descriptions of what each one permits, requires, and prohibits. The README states that the site's goal is to be accurate, non-judgmental, and understandable, and that it is deliberately not comprehensive.

The repository is maintained by GitHub. It is not just a website. The license catalog in the _licenses folder is regularly imported into GitHub.com and used as the source of licenses shown when creating a new repository, as the data behind the GitHub Licenses API, and as the basis for GitHub's license detection feature. The license detection is implemented by the Licensee project, which the README references as a downstream consumer of the catalog.

The audience for the website is developers who are starting a new open source project and need to choose a license. The audience for the repository itself is developers who want to run the site locally, add a new license to the catalog, or contribute a translation.

How the Catalog Is Structured: Jekyll Collection with YAML Front Matter

Each license in the catalog is a single file stored in the _licenses directory. The file consists of YAML front matter followed by the license text in plain text. The YAML front matter documents the license's properties using a fixed schema.

Required fields in the front matter include the full license name (keyed as title, matching the SPDX identifier at spdx.org), the SPDX short identifier (spdx-id), a human-readable description, instructions for how to apply the license (how), a map of three example projects that use the license (using), and three lists of rules: permissions, conditions, and limitations.

The rules system uses named identifiers. In the permissions list, for example, commercial-use means the software may be used for commercial purposes, and patent-use means the license provides an express grant of patent rights. In the conditions list, include-copyright requires that a copy of the license and copyright notice accompany the software. In the limitations list, liability means the license includes a limitation of liability. All rule names and their meanings are defined in _data/rules.yml.

Optional fields include featured (whether the license appears on the main page), hidden (whether to exclude it from the full licenses list), nickname (a common short name like GPLv3), note (additional information), and redirect_from for URL backward compatibility.

Running choosealicense.com Locally

The site is a Jekyll application. The README lists cmake and make as system dependencies and provides platform-specific install instructions.

On macOS using Homebrew:

brew install make cmake

On Linux using apt-get:

sudo apt-get install make cmake

After installing the system dependencies, the README gives these steps to clone, bootstrap, and start the server:

git clone https://github.com/github/choosealicense.com.git --recursive
cd choosealicense.com
./script/bootstrap
./script/server

The --recursive flag is required because the repository includes a git submodule. After the server starts, the site is available at http://localhost:4000.

The site is deployed from GitHub Actions using a workflow in .github/workflows/deploy.yml. The README notes that Jekyll Polyglot, the plugin used for multi-language support, is not a standard GitHub Pages plugin, so the deployment workflow builds and deploys through Actions rather than through the standard GitHub Pages mechanism.

Auto-Populated Variables and How GitHub Uses the Catalog

When GitHub creates a new repository and a user selects a license, GitHub replaces template variables in the license text with repository-specific values. The README documents the available variables: fullname (the full name or username of the repository owner), login (the owner's username), email (the owner's primary email), project (the repository name), description (the repository description), year (the current year), and projecturl (the repository URL).

These variables allow a license like MIT, which contains a copyright year and owner name placeholder, to be automatically filled in when GitHub generates the license file. The Licensee project, which GitHub uses downstream, reads the license catalog to detect which license a repository is using based on its LICENSE file.

The CONTRIBUTING.md file documents a selection criterion for adding licenses to the catalog: not comprehensive is stated as an explicit goal, meaning the project will not catalog every available open source license. Licenses must be either popular or fill a meaningful gap in the spectrum from strongly conditional to unconditional.

Multi-Language Support and the Translation Workflow

The site supports multiple languages. Each language is served under its own URL prefix, such as /fr/ for French. The README states that the interface and the non-legal license summaries are translatable, but the legal text of each license is never translated. This is a deliberate design choice: translating legal text introduces risk of misinterpretation.

Translations are maintained through a combination of keyed YAML files and Markdown files per language. The README references TRANSLATING.md for instructions on adding or updating a translation, and WEBLATE.md for community translation via the Weblate platform.

The translation architecture uses jekyll-polyglot to generate language-specific pages from the same source files. The site currently includes completed translations for several languages and work-in-progress translations for others, as listed in the README's language table.

Limitations: Intentionally Small Catalog, No Legal Advice, No Comprehensive Coverage

The README is explicit that the catalog is not comprehensive. It covers licenses that the project maintainers consider significant, either because they are widely used or because they represent distinct points on the spectrum from permissive to copyleft. Less common licenses are excluded by design.

The site does not provide legal advice. The license descriptions and the permissions, conditions, and limitations summaries are intended to aid understanding, not to substitute for a lawyer's analysis. Organizations with compliance requirements or patent concerns should treat choosealicense.com as a starting point, not a final authority.

The license catalog is regularly imported into GitHub.com, but the import is not instantaneous. A license added to the repository will not immediately appear in GitHub's repository creation workflow. The README references this import process without documenting its frequency.

The site does not cover software licenses that are proprietary, source-available, or non-open-source. It also does not cover licenses for hardware, fonts, or creative works, except in the non-software license guidance pages.

Alternative: SPDX License List

The SPDX License List, maintained by the Linux Foundation, is the most comprehensive catalog of open source and free software licenses. It includes hundreds of licenses with machine-readable identifiers, and it is the source of the spdx-id values that choosealicense.com uses in its front matter.

The difference in approach is focus. choosealicense.com is designed for a developer who needs to make a quick, informed decision about which license to apply to a new project. It presents a small, curated set with plain-language explanations. The SPDX License List is exhaustive and is designed for legal and compliance tooling that needs to identify and compare any license a piece of software might use.

For a developer starting a project, choosealicense.com is the faster path to a decision. For a compliance team auditing a large codebase for license compatibility, the SPDX License List is the more appropriate resource.

Editorial conclusion

choosealicense.com is the right reference for developers who want a clear, non-judgmental comparison of common open source licenses before choosing one for a project. It is not the right resource for comprehensive legal guidance: the site's own goal statement says it is intentionally not comprehensive and does not attempt to list every available license. Lawyers and organizations with specific compliance requirements should consult a legal professional. If you want to add a license to the catalog or contribute a translation, verify that the license meets the criteria in CONTRIBUTING.md, because the project deliberately limits the catalog to licenses that matter and will reject additions that do not meet its criteria.

Frequently asked questions

Official sources

1. github/choosealicense.com on GitHub
2. Issues
3. License: MIT
4. Project website
5. README