# Where to get started with pyproject.toml? **URL:** \ **Category:** Python Help\ **Created:** [August 5, 2020, 8:52am UTC](https://discuss.python.org/t/where-to-get-started-with-pyproject-toml/4906 "2020-08-05T08:52:37Z")\ **Posts on this page:** 20\ **Page:** 1
**Author:** ![Lawouach](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/lawouach/32/2451_2.png) [@Lawouach](https://discuss.python.org/u/Lawouach)\ **Post date:** [August 5, 2020, 8:52am UTC](https://discuss.python.org/t/where-to-get-started-with-pyproject-toml/4906/1 "2020-08-05T08:52:38Z")
Hey all, I have toi create a new Python package so I thought, for once, I’d try to be doing the right thing and use the new pyproject.toml as well introduced by Brett in [https://snarky.ca/what-the-heck-is-pyproject-toml/](https://snarky.ca/what-the-heck-is-pyproject-toml/) But I goty confused quickly unfortunately. It seems no official documentation exists yet around pyproject.toml and the PEPs aren’t user docs. It appears Pypa and the Python docs both continue talking about using setup.py. I was wondering if there was a place I wasn’t aware of perhaps? Or maybe some help to document it if I can find the time, but then where to start? Cheers, ---
**Author:** ![uranusjr](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/uranusjr/32/103_2.png) [@uranusjr](https://discuss.python.org/u/uranusjr)\ **Post date:** [August 6, 2020, 5:08am UTC](https://discuss.python.org/t/where-to-get-started-with-pyproject-toml/4906/2 "2020-08-06T05:08:01Z")
The post you linked contains the three lines you need in `pyproject.toml`. Use `setup.py` for everything else like you used to. If you’re looking to adapt the _three_-file set-up (a three-line `pyproject.toml`, a `setup.py` shim, and `setup.cfg`) as suggested in Brett’s post, here’s documentation on how to write `setup.cfg`: [https://setuptools.readthedocs.io/en/latest/setuptools.html#configuring-setup-using-setup-cfg-files](https://setuptools.readthedocs.io/en/latest/setuptools.html#configuring-setup-using-setup-cfg-files) ---
**Author:** ![Lawouach](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/lawouach/32/2451_2.png) [@Lawouach](https://discuss.python.org/u/Lawouach)\ **Post date:** [August 6, 2020, 5:36am UTC](https://discuss.python.org/t/where-to-get-started-with-pyproject-toml/4906/3 "2020-08-06T05:36:34Z")
Hello Tzu-ping, Thanks for the feedback. So as I understand you, `pyproject.toml` is only meant to declare the build configuration and we still need setup.py/cfg for defining what’s inside the built package, right? ---
**Author:** ![uranusjr](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/uranusjr/32/103_2.png) [@uranusjr](https://discuss.python.org/u/uranusjr)\ **Post date:** [August 6, 2020, 6:05am UTC](https://discuss.python.org/t/where-to-get-started-with-pyproject-toml/4906/4 "2020-08-06T06:05:59Z")
Correct. To be pedantic, `setup.py` and/or `setup.cfg` is needed for defining what’s inside the built package _if you choose to use setuptools_. But most people use setuptools anyway. ---
**Author:** ![b11c](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/b11c/32/2350_2.png) [@b11c](https://discuss.python.org/u/b11c)\ **Post date:** [August 10, 2020, 4:34pm UTC](https://discuss.python.org/t/where-to-get-started-with-pyproject-toml/4906/5 "2020-08-10T16:34:56Z")
Well, you an also use a tool that takes care of that for you, such as poetry: [https://python-poetry.org/](https://python-poetry.org/) ---
**Author:** ![bittner](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/bittner/32/1239_2.png) [@bittner](https://discuss.python.org/u/bittner)\ **Post date:** [August 11, 2020, 2:32pm UTC](https://discuss.python.org/t/where-to-get-started-with-pyproject-toml/4906/6 "2020-08-11T14:32:27Z")
That still needs further clarification: We now have 3 files (`pyproject.toml`, `setup.py`, `setup.cfg`) instead of just 1 (`setup.py`). That sounds like a huge progress! Ha? 🙄 That can’t be the appropriate answer. There must be a better way! ---
**Author:** ![uranusjr](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/uranusjr/32/103_2.png) [@uranusjr](https://discuss.python.org/u/uranusjr)\ **Post date:** [August 11, 2020, 4:27pm UTC](https://discuss.python.org/t/where-to-get-started-with-pyproject-toml/4906/7 "2020-08-11T16:27:50Z")
Forgive me if what I’m going to write feels like ranting; I’ve had this discussion with many people and have many thoughts on this topic. The number of files does not correlate to “goodness”. Each configuration file is a signal to people reading your repository (including your future self) what tools the project uses. You see `webpack.config.js` and you know a project uses Webpack, not (say) Gulp; `pytest.ini` for pytest as the designated test runner, `noxfile.py` for Nox, etc. Each of the three files in this set-up signals different aspects of your project’s tooling. `pyproject.toml` means this is a Python project. `setup.cfg` means it is using setuptools for packaging. `setup.py` means it also uses setuptools during development (note that you don’t need this file if you don’t call `python setup.py` directly; pip recognise `setup.cfg` and can run it independently). Can we use only one file? Absolutely. But I’d prefer not doing that, personally. I do regnoise that a lot of people don’t agree with my preference. And that’s OK, since it’s just a subjective preference. But on the other hand, it is also important to recognise the reasoning behind the preference to multiple configuration files. What a better way means depends on the people who use the tools (and remember, project maintainers are usually the most involved users of the project itself!), and it doesn’t help to complain when you and the tool designers disagree. If you absolutely can’t stand this “clutter” (as some of my friends put it), there are other tools that may fit your preference. Poetry (mentioned above) and Flit are both alternatives to setuptools, and both of them only use `pyproject.toml` as the One Configuration File. (There is also discussion to add `pyproject.toml` support to setuptools as well, but don’t hold your breath waiting for it.) But regardless of the tool you choose, it’s only natural to sometimes disagree with the design. We all learn to live with the differences. ---
**Author:** ![Lawouach](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/lawouach/32/2451_2.png) [@Lawouach](https://discuss.python.org/u/Lawouach)\ **Post date:** [August 12, 2020, 7:30am UTC](https://discuss.python.org/t/where-to-get-started-with-pyproject-toml/4906/8 "2020-08-12T07:30:01Z")
Personally, it doesn’t really pain me we have many files but it does that the explanation for them is either buried deep into the docs somewhere or not transparent at all. It was more a documentation issue for my side than an infrastructure issue. ---
**Author:** ![b11c](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/b11c/32/2350_2.png) [@b11c](https://discuss.python.org/u/b11c)\ **Post date:** [February 27, 2021, 7:29pm UTC](https://discuss.python.org/t/where-to-get-started-with-pyproject-toml/4906/9 "2021-02-27T19:29:35Z")
We don’t actually - `setuptools` is fully PEP 517 compliant, so you just need `pyproject.toml`. ---
**Author:** ![bittner](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/bittner/32/1239_2.png) [@bittner](https://discuss.python.org/u/bittner)\ **Post date:** [February 28, 2021, 11:50am UTC](https://discuss.python.org/t/where-to-get-started-with-pyproject-toml/4906/10 "2021-02-28T11:50:31Z")
> [@b11c](#): > > We don’t actually - `setuptools` is fully PEP 517 compliant, so you just need `pyproject.toml` . Do know of some sample source code, ideally an open source project, that shows how this is done with only `pyproject.toml`? ---
**Author:** ![b11c](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/b11c/32/2350_2.png) [@b11c](https://discuss.python.org/u/b11c)\ **Post date:** [February 28, 2021, 1:10pm UTC](https://discuss.python.org/t/where-to-get-started-with-pyproject-toml/4906/11 "2021-02-28T13:10:24Z")
It’s right there in the `setuptools` documentation: [Build System Support — setuptools 53.1.0 documentation](https://setuptools.readthedocs.io/en/latest/build_meta.html) ---
**Author:** ![Lawouach](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/lawouach/32/2451_2.png) [@Lawouach](https://discuss.python.org/u/Lawouach)\ **Post date:** [March 1, 2021, 9:04am UTC](https://discuss.python.org/t/where-to-get-started-with-pyproject-toml/4906/12 "2021-03-01T09:04:43Z")
To be fair, on that page, it says you need the pyproject.toml _and_ a setup.cfg file. Maybe that’s just for an example but that’s the confusion some of us were raising. I’m guessing, projects with just the pyproject.toml end up adding every metadata, found in setup.cfg, in the pyproject.toml file, right? ---
**Author:** ![b11c](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/b11c/32/2350_2.png) [@b11c](https://discuss.python.org/u/b11c)\ **Post date:** [March 1, 2021, 9:46am UTC](https://discuss.python.org/t/where-to-get-started-with-pyproject-toml/4906/13 "2021-03-01T09:46:31Z")
Oh you’re right, that’s a good point, I missed that – especially as the syntaxes for TOML and `.cfg` are so similar… 🙄 So yes, for now you need both, but there is currently an [ongoing discussion](https://github.com/pypa/setuptools/issues/1688) which shows a lot of promise… ---
**Author:** ![uranusjr](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/uranusjr/32/103_2.png) [@uranusjr](https://discuss.python.org/u/uranusjr)\ **Post date:** [March 1, 2021, 10:12am UTC](https://discuss.python.org/t/where-to-get-started-with-pyproject-toml/4906/14 "2021-03-01T10:12:07Z")
> [@b11c](#): > > there is currently an [ongoing discussion](https://github.com/pypa/setuptools/issues/1688) which shows a lot of promise… There are a lot of people showing interest in the feature, but no-one committing resources to implement it yet. Not exactly what I’d call “a lot of promise”. ---
**Author:** ![Lawouach](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/lawouach/32/2451_2.png) [@Lawouach](https://discuss.python.org/u/Lawouach)\ **Post date:** [March 1, 2021, 10:39am UTC](https://discuss.python.org/t/where-to-get-started-with-pyproject-toml/4906/15 "2021-03-01T10:39:36Z")
Since I’m the one who created this thread, I want to say publicly though, that once I had spent a bit more time reading through the rich documentation, things looked to make more sense indeed. All in all, [my project](https://github.com/chaostoolkit/chaostoolkit) moved a the new scheme. It wasn’t that hard and I am happy I could get away from setup.py almost entirely (it’s almost empty now). ---
**Author:** ![ilayn](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/ilayn/32/5769_2.png) [@ilayn](https://discuss.python.org/u/ilayn)\ **Post date:** [April 13, 2022, 2:50pm UTC](https://discuss.python.org/t/where-to-get-started-with-pyproject-toml/4906/16 "2022-04-13T14:50:12Z")
Disclosure: I am an average Python coder I am occasionally helping folks in SciPy as a core maintainer and I have my own pure Python package harold for which I decided to follow the latest greatest standards. I can’t say I don’t regret it. I’ll try to explain what the whole user journey currently is; - There is a very obvious expert blindness seeping into the docs. I just wanted to write a toml or yaml or cfg with ?ml file syntax but ended up reading PEP 517 because everywhere on the docs mentions PEP 517 or 660 or 518 or any other random number. If people think that average users will understand that text without being a somewhat expert on packaging we have much bigger problems. - There is no clean cut description what these files say. Also the documentation language is, much to my regret, full of jargon. Take [setuptools Quickstart - setuptools 62.1.0.post20220410 documentation](https://setuptools.pypa.io/en/latest/userguide/quickstart.html) it says basic use. It uses setup.py and pyproject.toml. One of them is discouraged and the other one is experimental. What am I going to use only setup.cfg? Are these three options or I need all? Then I go up the page because I need more info apparently and it says read stuff at the bottom of the page. Very well. There is something called [setuptools Quickstart - setuptools 62.1.0.post20220410 documentation](https://setuptools.pypa.io/en/latest/userguide/quickstart.html#transitioning-from-setup-py-to-setup-cfg) That seems relevant because that’s what I am doing. But below that it points to [Packaging Python Projects — Python Packaging User Guide](https://packaging.python.org/en/latest/tutorials/packaging-projects/) which asks me to change my project structure to so-called `src` structure which I didn’t have before. Is this what the new way is? No answer there. Can I keep my project structure? I can’t tell. - Then I start googling and I understand that setup.py is the legacy way. So then I need pyproject file which I learn that from setuptools it is an option. But the actual setuptools file is called setup.cfg. I mean why? Why not setuptools.cfg? OK nevermind, not my problem. So I read Brett’s blog post [What the heck is pyproject.toml?](https://snarky.ca/what-the-heck-is-pyproject-toml/) Ok probably more advanced people can understand and appreciate that. Not me because I still don’t get which file I should use let alone their content. - So I start randomly doing things on my own adding lines removing lines duplicating them etc. and I start hitting [[BUG] · Issue #3197 · pypa/setuptools · GitHub](https://github.com/pypa/setuptools/issues/3197) Thanks to @abravalheri 's kind help I manage to straighten some kinks both mentally and code-wise but still this is seriously complicated compared to Python’s typical straightforward and expressive style. Note that, I am not this baffled while dealing with SciPy’s Fortran/C/C++ build system with n different compilers. But with this new development, I can’t even get the 10000ft high-level strategy around these tools let alone actually following tutorials. Anyways, long story short, where can I attempt to contribute to the docs for a unapologetically beginner level tutorial for this? Because clearly noone else would do it. I don’t know what I am doing and that makes me a perfect candidate for it. And as a side note, please don’t use non-deterministic word randomly in the docs. If you know what I mean… ---
**Author:** ![sinoroc](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/sinoroc/32/1607_2.png) [@sinoroc](https://discuss.python.org/u/sinoroc)\ **Post date:** [April 13, 2022, 6:09pm UTC](https://discuss.python.org/t/where-to-get-started-with-pyproject-toml/4906/17 "2022-04-13T18:09:47Z")
Not much of an answer, but maybe I would recommend not using _setuptools_, and use any other modern build tool instead, [_flit_](https://pypi.org/project/flit/) might be a good choice, [_`pdm`_](https://pypi.org/project/pdm/) is another one. Otherwise everything you mentioned rings true to me. Documentation is not as good as it should be, but it is improving by the day, so is Python packaging in general. Another user posted a somewhat similar post with the idea of documenting their own journey into Python packaging with fresh eyes, you might find something useful in there for you. Here it is: - [Modernising my packages - am I thinking about this all wrong?](https://discuss.python.org/t/modernising-my-packages-am-i-thinking-about-this-all-wrong/14558) And the output: - [css/pypa-the-missing-outline.md at pypi · cameron-simpson/css · GitHub](https://github.com/cameron-simpson/css/blob/pypi/doc/pypa-the-missing-outline.md) ---
**Author:** ![ilayn](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/ilayn/32/5769_2.png) [@ilayn](https://discuss.python.org/u/ilayn)\ **Post date:** [April 13, 2022, 9:12pm UTC](https://discuss.python.org/t/where-to-get-started-with-pyproject-toml/4906/18 "2022-04-13T21:12:57Z")
Ah thanks a lot indeed, that thread is more eloquent than what I have written down. I’ll follow that one a bit carefully. ---
**Author:** ![sinoroc](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/sinoroc/32/1607_2.png) [@sinoroc](https://discuss.python.org/u/sinoroc)\ **Post date:** [April 13, 2022, 9:42pm UTC](https://discuss.python.org/t/where-to-get-started-with-pyproject-toml/4906/19 "2022-04-13T21:42:30Z")
If you have to deal with C extensions, then you might want to follow and contribute to this topic as well: ["Modern" way to build packages with C (Cython) extensions](https://discuss.python.org/t/modern-way-to-build-packages-with-c-cython-extensions/15050) ---
**Author:** ![cameron](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/cameron/32/2658_2.png) [@cameron](https://discuss.python.org/u/cameron)\ **Post date:** [April 13, 2022, 10:54pm UTC](https://discuss.python.org/t/where-to-get-started-with-pyproject-toml/4906/20 "2022-04-13T22:54:48Z")
By Ilhan Polat via Discussions on [Python.org](http://Python.org) at 13Apr2022 21:23: > Ah thanks a lot indeed, that thread is more eloquent than what I have > written down. I’ll follow that one a bit carefully. BTW, I’d welcome feedback on the overview docs from you as a user of the doc (rather than the PyPA guys, who will be reading it as people who already know how all this stuff works). Could you have a read of this: ``` https://github.com/cameron-simpson/css/blob/pypi/doc/pypa-the-missing-outline.md ``` and report your impressions or suggestions? I’m going to try to get it included in the PyPA docs up the front where the tutorial is mentioned. Thanks, Cameron Simpson [cs@cskk.id.au](mailto:cs@cskk.id.au) [Next page](https://discuss.python.org/t/where-to-get-started-with-pyproject-toml/4906.md?page=2)