openfootball worldcup keeps every World Cup in a plain text folder

One directory per tournament, from 1930 to 2026

The top level of the repository is a list of years, and each year is a folder named after the year, the host nation and the edition, separated by a double hyphen.

The first entries are 1930--uruguay/, 1934--italy/, 1938--france/, 1950--brazil/, 1954--switzerland/, 1958--sweden/, 1962--chile/, 1966--england/, 1970--mexico/ and 1974--west_germany/.

The sequence continues through 1978--argentina/, 1982--spain/, 1986--mexico/, 1990--italy/, 1994--usa/, 1998--france/, 2002--south_korea-n-japan/, 2006--germany/, 2010--south_africa/, 2014--brazil/, 2018--russia/, 2022--qatar/ and 2026--canada-usa-mexico/.

Two details in that naming are worth noticing. Uruguay 1930 opens the list, and there is no 1942 or 1946 entry, which matches the wartime cancellations rather than a gap in the naming scheme. The double hyphen also means the separator can never collide with the hyphen in a name such as south_korea-n-japan, and it sorts chronologically as plain text.

This is a dataset repository, and the project entry point says so plainly: the primary language is not even recorded, because there is no program in it. The unit of value is the file, and the directory structure is the index.

Football.TXT keeps groups, kickoff times and scorers in one file

The format is called Football.TXT, and the project describes it as future-proof and evergreen, meaning a text file that stays readable as the sport changes. Here is a fragment of the 2022 edition as it appears in the documentation.

= World Cup 2022    # in Qatar, November 20 - December 18

Group A  | Qatar      Ecuador        Senegal        Netherlands
Group B  | England    Iran           USA            Wales

A file starts with a title line beginning with an equals sign, followed by a comment giving the host and the date range. Groups are then listed with a pipe separator after the group name.

Below the groups come the matches, introduced by a section marker. The documentation uses a small square bullet to open a block, and a matchday line such as a group and matchday number, then a date line, then one line per match.

▪ Group A, Matchday 1
Sun Nov 20
  19:00      Qatar   v Ecuador  0-2 (0-2)    @ Al Bayt Stadium, Al Khor

The scoreline carries the half-time score in parentheses, and the venue follows an at sign. Goal scorers are listed on a continuation line beneath the match, with minutes in apostrophes and a penalty marker. The 2022 example goes further than that: it lists the shootout kicks with a running tally, and it prints the starting lineups for both teams with substitutions marked by their minutes.

That density is the format's strength and its cost. A parser gets a lot for free, since the structure is regular, and it also has to deal with optional blocks such as the shootout and the lineups that some editions include and others omit.

Five source collections sit beside the year folders

The year folders are the curated view. Beside them are five directories with names that indicate where the raw data comes from: rsssf/, wikipedia/, planetworldcup/, min/ and more/.

The naming of min/ and more/ suggests two tiers of coverage, a minimal set and a fuller one, though the repository does not explain the split in the README. The other three are named after sources, which tells you the project keeps material from several places rather than treating one feed as canonical. A reader who wants to know where a particular line of data came from has that directory structure to work with.

Alongside the data sit four documentation files: COUNTRIES.md, NOTES.md, NOTES.MORE.md and LICENSE.md. The country list is there to be the reference vocabulary that team names in the match files are drawn from, which is the kind of detail that matters when you join two tables on a name. The two notes files carry the editorial commentary, and LICENSE.md records the terms.

This layout has a practical consequence. A project that keeps both curated year folders and raw source folders is a project where the same fixture can appear twice, in two shapes, and where you have to decide which one your pipeline reads. That decision is left to the reader.

The build-your-own step is documented elsewhere

The README closes with a section titled Build Your Own worldcup.db Database or worldcup.json/.csv Datasets, and the answer it gives is a single word: yes, followed by a pointer to the project site rather than an explanation in the repository.

The distinction matters. The football.db project is described as a free open public domain football database and schema for use in any programming language, built on the same Football.TXT datasets. The text files are the source of truth for humans and for version control, and the database and the JSON and CSV exports are derived artefacts generated from them.

There is a leftover trace of that pipeline in the release history. The only published release is v2018.06.22, described as worldcup.db built on 2018.06.22. A single release, dated to the 2018 tournament and named after the day the database was built, tells you the artefact is generated rather than maintained, and that the generated output can lag the text by a long way.

So if your plan is to consume worldcup.db or the JSON and CSV exports, check the date on the artefact before trusting it. If your plan is to parse the Football.TXT files, that is the layer the project actually keeps current.

What the format does not carry, and who the data suits

The match files describe fixtures, results, scorers, venues and sometimes lineups. They are organised around the tournament: groups, matchdays, third place play-off and final. There is no indication in the repository of a player registry, a club league structure, or a per-match identifier designed to be a stable primary key across editions.

That sets the audience. A developer building a bracket, a fixtures widget, a score predictor demo or a set of test fixtures for a charting library gets exactly what they need, in a format they can read with a regular expression or a small parser, in a licence that does not require attribution.

The alternative for most teams is a live sports data feed. The difference in approach is not accuracy, which cannot be judged from here, but shape and terms. A live feed is a service you call, with a schema you do not control, results that change under you, and a commercial licence attached. Football.TXT is a set of files you vendor, that diff cleanly in version control, that you can extend with your own corrections, and that come with a CC0 public domain dedication. For a demo, a teaching example or a reproducible analysis, that is a much better trade than a dependency you have to keep pointed at a changing API.

CC0 data with a curated layer and an old generated artefact

The licence is CC0-1.0, and the project describes the contents as free open public domain football data. In practice that means the files carry no attribution requirement, which is why they are pleasant to ship inside an application, a notebook or a teaching pack without a credits screen.

The maintenance picture is mixed, and the two halves should not be confused. The last push to the master branch was on 2026-08-22, so the text data is being touched, and the description notes coverage that includes the 2026 finals and World Cup qualifiers. The 2026 example in the documentation is complete in the way the documentation expects, with group tables, matchdays, a third place play-off and a final decided after extra time.

Against that, the published release list has exactly one entry, the 2018 database build, and the project says it is currently at no numbered version beyond that artefact. A repository with no releases, no tags worth depending on and no schema file means version pinning has to happen at the file or directory level, and a consumer who needs a stable contract has to freeze a copy themselves.

None of this makes the data wrong. It makes the maintenance model explicit: the files are maintained by hand, the generated database is not, and the two will drift.

Editorial conclusion

openfootball worldcup fits a developer building a fixture viewer, a statistics demo or a test fixture set who wants the data in a diffable text file under a licence that lets them ship it. It does not fit a product that needs live scores, player-level records or a maintained relational schema, since the repository holds no API and no query layer. Before using it, read the per-tournament directory for your competition and check the notes files, since the provenance of each edition and the qualifiers coverage differ between collections.

Frequently asked questions

Official sources

1. License: CC0-1.0
2. openfootball/worldcup on GitHub
3. Project website
4. README
5. Releases