|
| 1 | +--- |
| 2 | +layout: single |
| 3 | +title: "Announcing Poetry 2.1.0" |
| 4 | +date: 2025-02-15 |
| 5 | +categories: [releases] |
| 6 | +tags: ["2.x", "2.1"] |
| 7 | +--- |
| 8 | + |
| 9 | +The Poetry team is pleased to announce the immediate availability of Poetry **2.1.0**. |
| 10 | + |
| 11 | +<!--more--> |
| 12 | + |
| 13 | +If you have a previous version of Poetry installed via `pipx`, |
| 14 | +getting Poetry **2.1.0** is as easy as: |
| 15 | + |
| 16 | +```bash |
| 17 | +$ pipx upgrade poetry |
| 18 | +``` |
| 19 | + |
| 20 | +If you used the [official installer](/docs/#installation), you can run: |
| 21 | + |
| 22 | +```bash |
| 23 | +$ poetry self update |
| 24 | +``` |
| 25 | + |
| 26 | +## Highlights |
| 27 | + |
| 28 | +### Support for alternative build backends in Poetry |
| 29 | + |
| 30 | +Poetry now supports customizable build backends, allowing greater flexibility based on your project's needs. Previously, |
| 31 | +Poetry exclusively used its own build backend, `poetry-core`, when creating packages via the `poetry build` command. |
| 32 | +Thanks to [PEP 621](https://peps.python.org/pep-0621/), this limitation is being lifted. |
| 33 | + |
| 34 | +With this change, the `poetry build` command will fully respect the `[build-system]` section defined in your |
| 35 | +`pyproject.toml` file. If the specified build backend differs from the version of `poetry-core` bundled with Poetry, the |
| 36 | +build will take place in an isolated environment. |
| 37 | + |
| 38 | +#### Defining custom build backends |
| 39 | + |
| 40 | +You can define the build backend in your `pyproject.toml`. For example, to use `maturin` as your build system, specify |
| 41 | +it like this: |
| 42 | + |
| 43 | +```toml |
| 44 | +[build-system] |
| 45 | +requires = ["maturin>=0.8.1,<0.9"] |
| 46 | +build-backend = "maturin" |
| 47 | +``` |
| 48 | + |
| 49 | +When running `poetry build`, Poetry will create an isolated environment with the specified requirements. |
| 50 | + |
| 51 | +#### Passing configuration to build systems |
| 52 | + |
| 53 | +If your chosen build system supports custom configuration settings, these can be passed via the new `--config-settings` |
| 54 | +parameter. Use the format `--config-settings <key>=<value>`. You can pass multiple settings by using the parameter |
| 55 | +repeatedly. |
| 56 | + |
| 57 | +For example, `poetry-core` allows you to specify a local version identifier during the build: |
| 58 | + |
| 59 | +```bash |
| 60 | +poetry build --config-settings local-version=some-local |
| 61 | +``` |
| 62 | + |
| 63 | +This parameter ensures compatibility with advanced use cases and third-party build backends. |
| 64 | + |
| 65 | +{{% note %}} |
| 66 | +You can pass configuration settings when building a dependency from source. |
| 67 | +Since such configuration settings are often platform-dependent this is done via a |
| 68 | +[config setting](/docs/configuration/#installerbuild-config-settingspackage-name). |
| 69 | +{{% /note %}} |
| 70 | + |
| 71 | +#### Default behavior when no build system is defined |
| 72 | + |
| 73 | +Per [PEP 517](https://peps.python.org/pep-0517/), a build tool should fall back to `setuptools` if no build system is |
| 74 | +defined in the `[build-system]` section of `pyproject.toml`. However, to avoid immediate disruption, Poetry will |
| 75 | +currently issue a **warning** in such cases and continue using the built-in `poetry-core` backend by default. |
| 76 | + |
| 77 | +{{% warning %}} |
| 78 | +This behavior will change in a future minor release so that Poetry will default to `setuptools` |
| 79 | +if no `[build-system]` section is defined. |
| 80 | +{{% /warning %}} |
| 81 | + |
| 82 | +### Experimental commands to manage Python installations |
| 83 | + |
| 84 | +Poetry now includes experimental [commands](/docs/cli/#python) to manage Python installations. |
| 85 | +You can install, list and remove Python versions, which you can use afterward to create project environments. |
| 86 | +For example, if you want to use Python 3.13 for your project, but you do not have it installed yet, you can run: |
| 87 | + |
| 88 | +```bash |
| 89 | +poetry python install 3.13 |
| 90 | +poetry env use 3.13 |
| 91 | +``` |
| 92 | + |
| 93 | +{{% note %}} |
| 94 | +The `python install` command uses [python-build-standalone](https://gregoryszorc.com/docs/python-build-standalone/main/), |
| 95 | +which has some quirks compared to standard Python installations. |
| 96 | +See their [documentation](https://gregoryszorc.com/docs/python-build-standalone/main/quirks.html) for more information. |
| 97 | +{{% /note %}} |
| 98 | + |
| 99 | +## Upcoming Changes |
| 100 | + |
| 101 | +### Defaulting to `setuptools` instead of `poetry-core` if no build system is defined |
| 102 | + |
| 103 | +Per [PEP 517](https://peps.python.org/pep-0517/), a build tool should fall back to `setuptools` if no build system is |
| 104 | +defined in the `[build-system]` section of `pyproject.toml`. However, to avoid immediate disruption, Poetry will |
| 105 | +currently issue a **warning** in such cases and continue using the built-in `poetry-core` backend by default. |
| 106 | +This behavior will change in a future minor release so that Poetry will default to `setuptools` |
| 107 | +if no `[build-system]` section is defined. |
| 108 | + |
| 109 | +## Changelog |
| 110 | + |
| 111 | +### Added |
| 112 | + |
| 113 | +- **Make `build` command build-system agnostic** ([#10059](https://github.com/python-poetry/poetry/pull/10059), |
| 114 | + [#10092](https://github.com/python-poetry/poetry/pull/10092)). |
| 115 | +- Add a `--config-settings` option to `poetry build` ([#10059](https://github.com/python-poetry/poetry/pull/10059)). |
| 116 | +- Add support for defining `config-settings` when building dependencies ([#10129](https://github.com/python-poetry/poetry/pull/10129)). |
| 117 | +- **Add (experimental) commands to manage Python installations** ([#10112](https://github.com/python-poetry/poetry/pull/10112)). |
| 118 | +- Use `findpython` to find the Python interpreters ([#10097](https://github.com/python-poetry/poetry/pull/10097)). |
| 119 | +- Add a `--no-truncate` option to `poetry show` ([#9580](https://github.com/python-poetry/poetry/pull/9580)). |
| 120 | +- Re-add support for passwords with empty usernames ([#10088](https://github.com/python-poetry/poetry/pull/10088)). |
| 121 | +- Add better error messages ([#10053](https://github.com/python-poetry/poetry/pull/10053), |
| 122 | + [#10065](https://github.com/python-poetry/poetry/pull/10065), |
| 123 | + [#10126](https://github.com/python-poetry/poetry/pull/10126), |
| 124 | + [#10127](https://github.com/python-poetry/poetry/pull/10127), |
| 125 | + [#10132](https://github.com/python-poetry/poetry/pull/10132)). |
| 126 | + |
| 127 | +### Changed |
| 128 | + |
| 129 | +- **`poetry new` defaults to "src" layout by default** ([#10135](https://github.com/python-poetry/poetry/pull/10135)). |
| 130 | +- Improve performance of locking dependencies ([#10111](https://github.com/python-poetry/poetry/pull/10111), |
| 131 | + [#10114](https://github.com/python-poetry/poetry/pull/10114), |
| 132 | + [#10138](https://github.com/python-poetry/poetry/pull/10138), |
| 133 | + [#10146](https://github.com/python-poetry/poetry/pull/10146)). |
| 134 | +- Deprecate adding sources without specifying `--priority` ([#10134](https://github.com/python-poetry/poetry/pull/10134)). |
| 135 | + |
| 136 | +### Fixed |
| 137 | + |
| 138 | +- Fix an issue where global options were not handled correctly when positioned after command options ([#10021](https://github.com/python-poetry/poetry/pull/10021), |
| 139 | + [#10067](https://github.com/python-poetry/poetry/pull/10067), |
| 140 | + [#10128](https://github.com/python-poetry/poetry/pull/10128)). |
| 141 | +- Fix an issue where building a dependency from source failed because of a conflict between build-system dependencies that were not required for the target environment ([#10048](https://github.com/python-poetry/poetry/pull/10048)). |
| 142 | +- Fix an issue where `poetry init` was not able to find a package on PyPI while adding dependencies interactively ([#10055](https://github.com/python-poetry/poetry/pull/10055)). |
| 143 | +- Fix an issue where the `@latest` descriptor was incorrectly passed to the core requirement parser ([#10069](https://github.com/python-poetry/poetry/pull/10069)). |
| 144 | +- Fix an issue where Boolean environment variables set to `True` (in contrast to `true`) were interpreted as `false` ([#10080](https://github.com/python-poetry/poetry/pull/10080)). |
| 145 | +- Fix an issue where `poetry env activate` reported a misleading error message ([#10087](https://github.com/python-poetry/poetry/pull/10087)). |
| 146 | +- Fix an issue where adding an optional dependency with `poetry add --optional` would not correctly update the lock file ([#10076](https://github.com/python-poetry/poetry/pull/10076)). |
| 147 | +- Fix an issue where `pip` was not installed/updated before other dependencies resulting in a race condition ([#10102](https://github.com/python-poetry/poetry/pull/10102)). |
| 148 | +- Fix an issue where Poetry freezes when multiple threads attempt to unlock the `keyring` simultaneously ([#10062](https://github.com/python-poetry/poetry/pull/10062)). |
| 149 | +- Fix an issue where markers with extras were not locked correctly ([#10119](https://github.com/python-poetry/poetry/pull/10119)). |
| 150 | +- Fix an issue where self-referential extras were not resolved correctly ([#10106](https://github.com/python-poetry/poetry/pull/10106)). |
| 151 | +- Fix an issue where Poetry could not be run from a `zipapp` ([#10074](https://github.com/python-poetry/poetry/pull/10074)). |
| 152 | +- Fix an issue where installation failed with a permission error when using the system environment as a user without write access to system site packages ([#9014](https://github.com/python-poetry/poetry/pull/9014)). |
| 153 | +- Fix an issue where a version of a dependency that is not compatible with the project's python constraint was locked. ([#10141](https://github.com/python-poetry/poetry/pull/10141)). |
| 154 | +- Fix an issue where Poetry wrongly reported that the current project's supported Python range is not compatible with some of the required packages Python requirement ([#10157](https://github.com/python-poetry/poetry/pull/10157)). |
| 155 | +- Fix an issue where the requested extras of a dependency were ignored if the same dependency (with same extras) was specified in multiple groups ([#10158](https://github.com/python-poetry/poetry/pull/10158)). |
| 156 | + |
| 157 | +### Docs |
| 158 | + |
| 159 | +- Sort commands by name in the CLI reference ([#10035](https://github.com/python-poetry/poetry/pull/10035)). |
| 160 | +- Add missing documentation for `env` commands ([#10027](https://github.com/python-poetry/poetry/pull/10027)). |
| 161 | +- Clarify that the `name` and `version` fields are always required if the `project` section is specified ([#10033](https://github.com/python-poetry/poetry/pull/10033)). |
| 162 | +- Add a note about restarting the shell for tab completion changes to take effect ([#10070](https://github.com/python-poetry/poetry/pull/10070)). |
| 163 | +- Fix the example for `project.gui-scripts` [#10121](https://github.com/python-poetry/poetry/pull/10121). |
| 164 | +- Explain how to include files as scripts in the project configuration ([#9572](https://github.com/python-poetry/poetry/pull/9572), |
| 165 | + [#10133](https://github.com/python-poetry/poetry/pull/10133)). |
| 166 | +- Add additional information on specifying required python versions ([#10104](https://github.com/python-poetry/poetry/pull/10104)). |
| 167 | + |
| 168 | +### poetry-core ([`2.1.0`](https://github.com/python-poetry/poetry-core/releases/tag/2.1.0)) |
| 169 | + |
| 170 | +- Fix an issue where inclusive ordering with post releases was inconsistent with PEP 440 ([#379](https://github.com/python-poetry/poetry-core/pull/379)). |
| 171 | +- Fix an issue where invalid URI tokens in PEP 508 requirement strings were silently discarded ([#817](https://github.com/python-poetry/poetry-core/pull/817)). |
| 172 | +- Fix an issue where wrong markers were calculated when removing parts covered by the project's python constraint ([#824](https://github.com/python-poetry/poetry-core/pull/824)). |
| 173 | +- Fix an issue where optional dependencies that are not part of an extra were included in the wheel metadata ([#830](https://github.com/python-poetry/poetry-core/pull/830)). |
| 174 | +- Fix an issue where the `__pycache__` directory and `*.pyc` files were included in sdists and wheels ([#835](https://github.com/python-poetry/poetry-core/pull/835)). |
0 commit comments