First I want to apologize, I think there are separate concerns that have made this discussion a little more confusing and difficult that I should have highlighted in my original post.
The separate, but interconnected, concerns as I see them are:
- What does the spec say and does it need clarifying?
- What is the advice for tools that read Python packaging TOML files?
- What is the advice for tools that write Python packaging TOML files?
- And perhaps, what is the plan in the standard library?
So going through each of these:
Specification
I had not intended for this thread to start a specification discussion, I was more thinking What do you think tools/libraries/scripts should do? However, now there has been so much input I have some thoughts:
I think specifying TOML 1.0 does require a PEP, because of the timeline of TOML versions and the PEPs I don’t see any evidence that TOML 1.0 was meant to be the version defined, or implied, by any of the packaging specifications:
TOML Specification Release History
| Version | Release Date | Link |
|---|---|---|
| v0.1.0 | 2013-03-17 | TOML: English v0.1.0 |
| v0.2.0 | 2013-09-24 | TOML: English v0.2.0 |
| v0.3.0 | 2014-11-10 | TOML: English v0.3.0 |
| v0.3.1 | 2014-11-11 | TOML: English v0.3.1 |
| v0.4.0 | 2015-02-12 | TOML: English v0.4.0 |
| v0.5.0 | 2018-07-10 | TOML: English v0.5.0 |
| v1.0.0-rc.1 | 2020-04-03 | TOML: English v1.0.0-rc.1 |
| v1.0.0 | 2021-01-11 | TOML: English v1.0.0 |
| v1.1.0 | 2025-12-18 | TOML: English v1.1.0 |
Comparably, here are the packaging PEPs that reference a TOML format file:
Python Packaging PEPs That Reference a TOML File
| PEP | File | Created | Link |
|---|---|---|---|
| PEP 517 | pyproject.toml |
2015-09-30 | PEP 517 – A build-system independent format for source trees | peps.python.org |
| PEP 518 | pyproject.toml |
2016-05-10 | PEP 518 – Specifying Minimum Build System Requirements for Python Projects | peps.python.org |
| PEP 621 | pyproject.toml |
2020-06-22 | PEP 621 – Storing project metadata in pyproject.toml | peps.python.org |
| PEP 631 | pyproject.toml |
2020-08-20 | PEP 631 – Dependency specification in pyproject.toml based on PEP 508 | peps.python.org |
| PEP 660 | pyproject.toml |
2021-03-30 | PEP 660 – Editable installs for pyproject.toml based builds (wheel based) | peps.python.org |
| PEP 751 | pylock.toml |
2024-07-24 | PEP 751 – A file format to record Python dependencies for installation reproducibility | peps.python.org |
So even though these PEPs were created from TOML v0.4 to TOML v1.0 none of them mention the version of TOML to use.
In fact PEP 751 links to the latest version of the TOML specification in the file format section: https://peps.python.org/pep-0751/#file-format
The format of the file is TOML.
I take all of this to mean that no specific version was intended, and I am interpreting that as the authors used term “TOML” as “the widely available version of TOML for Python users”.
So I am -1 on updating the specifications to which TOML version should be used, without a PEP. And my personal take is that any PEP should propose how packaging tools should transition to new versions, not just pin to a single version.
Consequentially, I reject the assertion that if someone writes a pyproject.toml file using TOML 1.1 specific syntax, then it is necessarily not spec compliant.
Reading Python package TOML files
With regards to what might be best practice, I think for tools which have a very limited user base it’s to adopt TOML 1.1 readers as soon as meets their cadence, it prevents raising errors on TOML 1.1 specific syntax in the future, most limited tooling does not have to worry if something is in the standard library or not.
For foundational tools and libraries, a concern brought up is that if they switch to being able to read TOML 1.1 then users that may introduce TOML 1.1 specific syntax and the tool will not tell them that’s an issue, and it will cause newer packages/projects not to work with tools that haven’t switched or are older.
It’s impossible to guess the real world impact of this, but I think there are a some orthogonal choices these tools and libraries should consciously make, first with regards to errors or warnings tools can:
- Read TOML 1.1 specific syntax and not worry about it, wait for real world user reports of issues
- Read TOML 1.1 specific syntax, but emit a warning if it is not TOML 1.0 compliant
- Error on TOML 1.1 specific syntax
I think all three choices are valid, but bear in mind that at some point TOML 1.1+ will be the commonly available TOML format, so even if a tool decides to reject TOML 1.1 specific syntax now, it will eventually become common.
Assuming tools adopt reading TOML 1.1 specific syntax the second choice is related to adoption strategy, two common choices are probably:
- Adopt TOML 1.1 for all cases
- Adopt TOML 1.1 as it becomes available in the standard library
I think both choices are valid but there are a couple of downsides for the latter, it is ambiguous for tools not based on Python, it creates the concern that was brought up: PopularTool™ would read TOML 1.1 specific syntax on one version of Python but fail on a different version.
As I don’t think this is a specification issue I would advise tools consider the options here and determine what is best for them, and listen to real world user feedback. Which choice seems sensible also might change over time, for example it might make sense to only support standard library TOML version for now but in 5 years it might make sense to vendor a TOML 1.1 reader for Python 3.14 as it might become mandated.
Writing Python package TOML files
I think we are all in agreement here that the preference would be to not use TOML 1.1 specific syntax, at least for the next 5+ years, so that packages and projects continue to work with older tools.
What is the plan for the Standard Library?
It would be great to have more insight on what the plan is in the Standard Library. I think adopting TOML 1.1 is generally a plus, but the wording of PEP 680 is a little concerning regarding the instruction to “treat minor revisions as bug fixes”. As a tool maintainer I find the most frustrating development moments when behavior changes have been implemented as bug fixes in CPython.