{"course":{"slug":"python-for-ai","title":"Python, from Zero, for AI","url":"https://addaly.com/learn/python-for-ai","level":"beginner","track":"build"},"lesson":{"slug":"packaging-with-pyproject","title":"pyproject.toml: making your project installable, and a command somebody can type","url":"https://addaly.com/learn/python-for-ai/packaging-with-pyproject","position":68,"of":89,"minutes":9,"answer":"A pyproject.toml with a name, version, dependencies and a [project.scripts] entry turns a folder into something pip can install and a command a colleague can run.","keyIdea":"A pyproject.toml with a name, version, dependencies and a [project.scripts] entry turns a folder into something pip can install and a command a colleague can run; pip install -e . links the source so edits take effect without reinstalling."},"body":{"format":"markdown","text":"## From a folder to a thing\n\nModule 3 laid out a project so that imports work. Module 5 pinned its dependencies. What remains is turning it into something that can be installed (by you on another machine, by a colleague, by a server) and run with one word instead of `python -m tagger.cli --input ...`.\n\nThe file that does it is `pyproject.toml`, at the root of the project:\n\n```toml\n[build-system]\nrequires = [\"setuptools>=68\"]\nbuild-backend = \"setuptools.build_meta\"\n\n[project]\nname = \"tagger\"\nversion = \"0.1.0\"\ndescription = \"Tag customer messages with a model\"\nrequires-python = \">=3.10\"\ndependencies = [\n    \"requests>=2.31,<3\",\n    \"pydantic>=2,<3\",\n]\n\n[project.optional-dependencies]\ndev = [\"pytest\", \"pyright\", \"ruff\"]\n\n[project.scripts]\ntagger = \"tagger.cli:main\"\n```\n\nEvery section does one job. `[build-system]` names the tool that turns the folder into an installable package; `setuptools` is the default and fine. `[project]` is the metadata and the runtime dependencies, the same list `requirements.txt` held, now with version ranges rather than exact pins, because a library states what it is compatible with while a deployment pins what it tested. `[project.optional-dependencies]` groups the tools you need to work on it but a user does not. `[project.scripts]` is the command.\n\nTOML is the format: sections in square brackets, `key = value`, strings quoted, lists in square brackets. It reads like an INI file with rules.\n\n## The layout it expects\n\n```\ntagger/\n├── pyproject.toml\n├── README.md\n├── src/\n│   └── tagger/\n│       ├── __init__.py\n│       ├── cli.py\n│       └── core.py\n└── tests/\n    └── test_core.py\n```\n\nWith `src/`, setuptools finds the package automatically. The reason for `src/` was given in module 3: it stops tests from importing the working copy by accident and proves the installed package works. Here it pays off again, because the same layout is what the build tool expects without configuration.\n\n## Editable install\n\n```bash\npip install -e .\n```\n\nThe dot is the current folder. `-e` is *editable*: instead of copying files into `site-packages`, pip writes a link to your `src/` folder, so every edit takes effect the next time Python imports the module, with no reinstall. Run it once per virtual environment. Add `[dev]` to get the development tools too:\n\n```bash\npip install -e \".[dev]\"\n```\n\nThe quotes protect the square brackets from the shell on macOS and Linux.\n\nAfter this, `import tagger` works from any directory, tests run against the real package, and `tagger` is a command.\n\n## The command\n\n`tagger = \"tagger.cli:main\"` means: when someone types `tagger`, import `tagger.cli` and call `main()`. That function takes no arguments (it reads `sys.argv` through `argparse`, as module 3 taught), and its return value becomes the exit code if it is an integer.\n\n```python\n# src/tagger/cli.py\nimport argparse\n\ndef main() -> int:\n    p = argparse.ArgumentParser(prog=\"tagger\")\n    p.add_argument(\"input\")\n    p.add_argument(\"--model\", default=\"qwen2.5:0.5b\")\n    args = p.parse_args()\n    ...\n    return 0\n```\n\nWhat pip generates is a tiny script on your `PATH` (in the venv's `bin/` or `Scripts/`) that does the import and the call. Because the import is live, edits to `main`'s body are picked up. Because the *name* `main` was copied from `[project.scripts]` into that script when it was generated, renaming the function breaks the command, and reinstalling alone does not mend it: the reinstall writes `main` again. Point the entry at the new name, then reinstall. The same holds for any edit to `pyproject.toml` itself (a new dependency, a new command, the version): an editable install follows your code, not your metadata.\n\n## Building a distribution\n\n```bash\npip install build\npython -m build\n```\n\nproduces `dist/tagger-0.1.0-py3-none-any.whl` and a `.tar.gz`. The wheel is a zip file with a manifest; `pip install dist/tagger-0.1.0-py3-none-any.whl` installs it on any machine with the right Python, no source tree needed. This is what you hand to a server, or upload.\n\n`twine upload --repository testpypi dist/*` publishes to TestPyPI, a free sandbox where the name does not need to be unique forever. Real PyPI is one flag away, and once a name is taken there it is taken; do not claim one you will not maintain.\n\n## `pipx`\n\nA command-line tool wants its own environment, so that its dependencies never collide with a project's. `pipx install tagger` (or `pipx install .` for a local one) creates a private venv for it and puts only the command on your `PATH`. It is how you should install any Python tool you run globally (`ruff`, `pyright`, `black`) and how a colleague should install yours.\n\n## Version and the other files\n\nBump `version` before each build; pip will not replace an installed `0.1.0` with a different `0.1.0`. `readme = \"README.md\"` in `[project]` puts the README on the package page. A `LICENSE` file is expected if you publish; without one, nobody may legally use it, whatever you intended.\n\n`uv` and `poetry` from module 5 read the same `pyproject.toml` and add lockfiles and faster resolvers on top. The file is the standard; the tools are choices.\n\n## Try this now\n\nGive the project from module 3 a `pyproject.toml`, install it editable, and run your command from a different directory. Rename `main` to `run`, watch the command fail, change `[project.scripts]` to `tagger = \"tagger.cli:run\"`, reinstall, and watch it work. Then `python -m build` and look inside the wheel with `unzip -l`."},"check":{"question":"A developer adds `[project.scripts] tagger = \"tagger.cli:main\"` to `pyproject.toml`, runs `pip install -e .`, and typing `tagger` in the terminal works. They then rename `main` to `run` inside `cli.py`, and the `tagger` command fails with `AttributeError: module 'tagger.cli' has no attribute 'main'`. Why did the editable install not pick up the change?","options":[{"text":"Editable installs cache the module's function table at install time and need `pip install -e .` again after any edit to a file, including a change inside a function body.","correct":false,"tempting":"Editable installs read your source files live; a change inside a function body would have been picked up without reinstalling."},{"text":"The generated command script imports `tagger.cli` live but looks up the attribute name written into it at install time, so the rename is invisible until reinstall.","correct":true},{"text":"Renaming a function changes the module's hash, which invalidates the editable link until the package is rebuilt.","correct":false,"tempting":"There is no such hash; editable installs link to the directory, and the function's name is irrelevant to the link."},{"text":"`[project.scripts]` requires the function to be called `main` by convention, and any other name is rejected.","correct":false,"tempting":"Any function name works, as long as the entry in `pyproject.toml` matches it."}]},"prev":{"slug":"running-a-type-checker","title":"Running a type checker: the bugs it finds that tests do not","url":"https://addaly.com/learn/python-for-ai/running-a-type-checker"},"next":{"slug":"profiling-where-time-goes","title":"Profiling: finding where the time actually goes before you optimise anything","url":"https://addaly.com/learn/python-for-ai/profiling-where-time-goes"},"authorship":"Founder and series editor: Dr Mustafa Mun. Written by AI models to a written standard. Source and assessment review continues. Academic review invited.","review":{"status":"Draft, open for academic review"},"cite":"Addaly (2026) 'pyproject.toml: making your project installable, and a command somebody can type', in Python, from Zero, for AI. Edited by M. Mun. Addaly. Available at: https://addaly.com/learn/python-for-ai/packaging-with-pyproject (Accessed: 21 November 2026).","licence":{"name":"CC BY-NC-SA 4.0","url":"https://creativecommons.org/licenses/by-nc-sa/4.0/"},"reader":{"schema":1,"title":"pyproject.toml: making your project installable, and a command somebody can type","courseTitle":"Python, from Zero, for AI","module":{"index":7,"slug":"objects-and-the-shape-of-programs","title":"Objects, generators and the shape a larger program takes"},"answer":null,"keyIdea":"A pyproject.toml with a name, version, dependencies and a [project.scripts] entry turns a folder into something pip can install and a command a colleague can run; pip install -e . links the source so edits take effect without reinstalling.","hero":{"kind":"plate","image":null,"alt":null,"caption":null},"blocks":[{"t":"h2","id":"from-a-folder-to-a-thing","runs":[{"text":"From a folder to a thing"}]},{"t":"p","runs":[{"text":"Module 3 laid out a project so that imports work. Module 5 pinned its dependencies. What remains is turning it into something that can be installed (by you on another machine, by a colleague, by a server) and run with one word instead of "},{"text":"python -m tagger.cli --input ...","code":true},{"text":"."}]},{"t":"p","runs":[{"text":"The file that does it is "},{"text":"pyproject.toml","code":true},{"text":", at the root of the project:"}]},{"t":"code","lang":"toml","label":"TOML","text":"[build-system]\nrequires = [\"setuptools>=68\"]\nbuild-backend = \"setuptools.build_meta\"\n\n[project]\nname = \"tagger\"\nversion = \"0.1.0\"\ndescription = \"Tag customer messages with a model\"\nrequires-python = \">=3.10\"\ndependencies = [\n    \"requests>=2.31,<3\",\n    \"pydantic>=2,<3\",\n]\n\n[project.optional-dependencies]\ndev = [\"pytest\", \"pyright\", \"ruff\"]\n\n[project.scripts]\ntagger = \"tagger.cli:main\""},{"t":"p","runs":[{"text":"Every section does one job. "},{"text":"[build-system]","code":true},{"text":" names the tool that turns the folder into an installable package; "},{"text":"setuptools","code":true},{"text":" is the default and fine. "},{"text":"[project]","code":true},{"text":" is the metadata and the runtime dependencies, the same list "},{"text":"requirements.txt","code":true},{"text":" held, now with version ranges rather than exact pins, because a library states what it is compatible with while a deployment pins what it tested. "},{"text":"[project.optional-dependencies]","code":true},{"text":" groups the tools you need to work on it but a user does not. "},{"text":"[project.scripts]","code":true},{"text":" is the command."}]},{"t":"p","runs":[{"text":"TOML is the format: sections in square brackets, "},{"text":"key = value","code":true},{"text":", strings quoted, lists in square brackets. It reads like an INI file with rules."}]},{"t":"h2","id":"the-layout-it-expects","runs":[{"text":"The layout it expects"}]},{"t":"code","lang":"","label":"Text","text":"tagger/\n├── pyproject.toml\n├── README.md\n├── src/\n│   └── tagger/\n│       ├── __init__.py\n│       ├── cli.py\n│       └── core.py\n└── tests/\n    └── test_core.py"},{"t":"p","runs":[{"text":"With "},{"text":"src/","code":true},{"text":", setuptools finds the package automatically. The reason for "},{"text":"src/","code":true},{"text":" was given in module 3: it stops tests from importing the working copy by accident and proves the installed package works. Here it pays off again, because the same layout is what the build tool expects without configuration."}]},{"t":"h2","id":"editable-install","runs":[{"text":"Editable install"}]},{"t":"code","lang":"bash","label":"Bash","text":"pip install -e ."},{"t":"p","runs":[{"text":"The dot is the current folder. "},{"text":"-e","code":true},{"text":" is "},{"text":"editable","i":true},{"text":": instead of copying files into "},{"text":"site-packages","code":true},{"text":", pip writes a link to your "},{"text":"src/","code":true},{"text":" folder, so every edit takes effect the next time Python imports the module, with no reinstall. Run it once per virtual environment. Add "},{"text":"[dev]","code":true},{"text":" to get the development tools too:"}]},{"t":"code","lang":"bash","label":"Bash","text":"pip install -e \".[dev]\""},{"t":"p","runs":[{"text":"The quotes protect the square brackets from the shell on macOS and Linux."}]},{"t":"p","runs":[{"text":"After this, "},{"text":"import tagger","code":true},{"text":" works from any directory, tests run against the real package, and "},{"text":"tagger","code":true},{"text":" is a command."}]},{"t":"h2","id":"the-command","runs":[{"text":"The command"}]},{"t":"p","runs":[{"text":"tagger = \"tagger.cli:main\"","code":true},{"text":" means: when someone types "},{"text":"tagger","code":true},{"text":", import "},{"text":"tagger.cli","code":true},{"text":" and call "},{"text":"main()","code":true},{"text":". That function takes no arguments (it reads "},{"text":"sys.argv","code":true},{"text":" through "},{"text":"argparse","code":true},{"text":", as module 3 taught), and its return value becomes the exit code if it is an integer."}]},{"t":"code","lang":"python","label":"Python","text":"# src/tagger/cli.py\nimport argparse\n\ndef main() -> int:\n    p = argparse.ArgumentParser(prog=\"tagger\")\n    p.add_argument(\"input\")\n    p.add_argument(\"--model\", default=\"qwen2.5:0.5b\")\n    args = p.parse_args()\n    ...\n    return 0"},{"t":"p","runs":[{"text":"What pip generates is a tiny script on your "},{"text":"PATH","code":true},{"text":" (in the venv’s "},{"text":"bin/","code":true},{"text":" or "},{"text":"Scripts/","code":true},{"text":") that does the import and the call. Because the import is live, edits to "},{"text":"main","code":true},{"text":"’s body are picked up. Because the "},{"text":"name","i":true},{"text":" "},{"text":"main","code":true},{"text":" was copied from "},{"text":"[project.scripts]","code":true},{"text":" into that script when it was generated, renaming the function breaks the command, and reinstalling alone does not mend it: the reinstall writes "},{"text":"main","code":true},{"text":" again. Point the entry at the new name, then reinstall. The same holds for any edit to "},{"text":"pyproject.toml","code":true},{"text":" itself (a new dependency, a new command, the version): an editable install follows your code, not your metadata."}]},{"t":"h2","id":"building-a-distribution","runs":[{"text":"Building a distribution"}]},{"t":"code","lang":"bash","label":"Bash","text":"pip install build\npython -m build"},{"t":"p","runs":[{"text":"produces "},{"text":"dist/tagger-0.1.0-py3-none-any.whl","code":true},{"text":" and a "},{"text":".tar.gz","code":true},{"text":". The wheel is a zip file with a manifest; "},{"text":"pip install dist/tagger-0.1.0-py3-none-any.whl","code":true},{"text":" installs it on any machine with the right Python, no source tree needed. This is what you hand to a server, or upload."}]},{"t":"p","runs":[{"text":"twine upload --repository testpypi dist/*","code":true},{"text":" publishes to TestPyPI, a free sandbox where the name does not need to be unique forever. Real PyPI is one flag away, and once a name is taken there it is taken; do not claim one you will not maintain."}]},{"t":"h2","id":"pipx","runs":[{"text":"pipx","code":true}]},{"t":"p","runs":[{"text":"A command-line tool wants its own environment, so that its dependencies never collide with a project’s. "},{"text":"pipx install tagger","code":true},{"text":" (or "},{"text":"pipx install .","code":true},{"text":" for a local one) creates a private venv for it and puts only the command on your "},{"text":"PATH","code":true},{"text":". It is how you should install any Python tool you run globally ("},{"text":"ruff","code":true},{"text":", "},{"text":"pyright","code":true},{"text":", "},{"text":"black","code":true},{"text":") and how a colleague should install yours."}]},{"t":"h2","id":"version-and-the-other-files","runs":[{"text":"Version and the other files"}]},{"t":"p","runs":[{"text":"Bump "},{"text":"version","code":true},{"text":" before each build; pip will not replace an installed "},{"text":"0.1.0","code":true},{"text":" with a different "},{"text":"0.1.0","code":true},{"text":". "},{"text":"readme = \"README.md\"","code":true},{"text":" in "},{"text":"[project]","code":true},{"text":" puts the README on the package page. A "},{"text":"LICENSE","code":true},{"text":" file is expected if you publish; without one, nobody may legally use it, whatever you intended."}]},{"t":"p","runs":[{"text":"uv","code":true},{"text":" and "},{"text":"poetry","code":true},{"text":" from module 5 read the same "},{"text":"pyproject.toml","code":true},{"text":" and add lockfiles and faster resolvers on top. The file is the standard; the tools are choices."}]},{"t":"h2","id":"try-this-now","runs":[{"text":"Try this now"}],"role":"try"},{"t":"p","runs":[{"text":"Give the project from module 3 a "},{"text":"pyproject.toml","code":true},{"text":", install it editable, and run your command from a different directory. Rename "},{"text":"main","code":true},{"text":" to "},{"text":"run","code":true},{"text":", watch the command fail, change "},{"text":"[project.scripts]","code":true},{"text":" to "},{"text":"tagger = \"tagger.cli:run\"","code":true},{"text":", reinstall, and watch it work. Then "},{"text":"python -m build","code":true},{"text":" and look inside the wheel with "},{"text":"unzip -l","code":true},{"text":"."}]}],"check":{"question":[{"text":"A developer adds "},{"text":"[project.scripts] tagger = \"tagger.cli:main\"","code":true},{"text":" to "},{"text":"pyproject.toml","code":true},{"text":", runs "},{"text":"pip install -e .","code":true},{"text":", and typing "},{"text":"tagger","code":true},{"text":" in the terminal works. They then rename "},{"text":"main","code":true},{"text":" to "},{"text":"run","code":true},{"text":" inside "},{"text":"cli.py","code":true},{"text":", and the "},{"text":"tagger","code":true},{"text":" command fails with "},{"text":"AttributeError: module 'tagger.cli' has no attribute 'main'","code":true},{"text":". Why did the editable install not pick up the change?"}],"options":[{"text":[{"text":"Editable installs cache the module’s function table at install time and need "},{"text":"pip install -e .","code":true},{"text":" again after any edit to a file, including a change inside a function body."}],"correct":false,"tempting":[{"text":"Editable installs read your source files live; a change inside a function body would have been picked up without reinstalling."}]},{"text":[{"text":"The generated command script imports "},{"text":"tagger.cli","code":true},{"text":" live but looks up the attribute name written into it at install time, so the rename is invisible until reinstall."}],"correct":true,"tempting":null},{"text":[{"text":"Renaming a function changes the module’s hash, which invalidates the editable link until the package is rebuilt."}],"correct":false,"tempting":[{"text":"There is no such hash; editable installs link to the directory, and the function’s name is irrelevant to the link."}]},{"text":[{"text":"[project.scripts]","code":true},{"text":" requires the function to be called "},{"text":"main","code":true},{"text":" by convention, and any other name is rejected."}],"correct":false,"tempting":[{"text":"Any function name works, as long as the entry in "},{"text":"pyproject.toml","code":true},{"text":" matches it."}]}],"order":[3,0,2,1],"why":null},"prev":{"slug":"running-a-type-checker","title":"Running a type checker: the bugs it finds that tests do not","minutes":9},"next":{"slug":"profiling-where-time-goes","title":"Profiling: finding where the time actually goes before you optimise anything","minutes":9}}}