|
| 1 | +--- |
| 2 | +date: 2026-08-11 |
| 3 | +authors: [cjames23] |
| 4 | +description: >- |
| 5 | + Hatch v1.18.0 brings dependency sources, workspace-wide builds, and a long list of fixes. |
| 6 | +categories: |
| 7 | + - Release |
| 8 | +--- |
| 9 | + |
| 10 | +# Hatch v1.18.0 |
| 11 | + |
| 12 | +Hatch [v1.18.0](https://github.com/pypa/hatch/releases/tag/hatch-v1.18.0) introduces dependency sources for redirecting packages at install time, a `--all` flag for building every workspace member at once, and a healthy batch of bug fixes. |
| 13 | + |
| 14 | +<!-- more --> |
| 15 | + |
| 16 | +## Dependency sources |
| 17 | + |
| 18 | +The new [`sources`](../../config/environment/sources.md) table redirects a dependency to somewhere other than the index it would normally come from — a local checkout, a Git branch, a URL, a private index, or another workspace member — **without touching the metadata you publish**. |
| 19 | + |
| 20 | +This is the workflow it is built for: you are developing against an unreleased fix in a library you depend on, and you want your environment to use your local clone while the wheel you ship keeps pointing at the released version. |
| 21 | + |
| 22 | +```toml config-example |
| 23 | +[project] |
| 24 | +dependencies = ["foo"] |
| 25 | + |
| 26 | +[tool.hatch.sources] |
| 27 | +foo = "./packages/foo" |
| 28 | +``` |
| 29 | + |
| 30 | +The top-level `[tool.hatch.sources]` table is an alias for the `default` environment, so the example above is shorthand for `[tool.hatch.envs.default.sources]`. |
| 31 | + |
| 32 | +Sources are matched to your dependencies by name after [PEP 503](https://peps.python.org/pep-0503/#normalized-names) normalization, and both project dependencies and environment dependencies are eligible. |
| 33 | + |
| 34 | +### Every kind of origin |
| 35 | + |
| 36 | +```toml config-example |
| 37 | +[tool.hatch.sources] |
| 38 | +# A local project directory, editable by default |
| 39 | +core = "./packages/core" |
| 40 | +# A non-editable install from a subdirectory |
| 41 | +utils = { path = "./monorepo", subdirectory = "packages/utils", editable = false } |
| 42 | +# A Git branch, tag, or revision |
| 43 | +client = { git = "https://github.com/example/client", branch = "main" } |
| 44 | +# An archive |
| 45 | +legacy = { url = "https://files.example.com/legacy-1.0.tar.gz" } |
| 46 | +# A private index, passed to the installer as --extra-index-url |
| 47 | +internal = { index = "https://pypi.example.com/simple" } |
| 48 | +# A workspace member, resolved through workspace.members |
| 49 | +my-pkg = { workspace = true } |
| 50 | +``` |
| 51 | + |
| 52 | +The `workspace = true` form is worth calling out: it lets you declare membership once in `workspace.members` and reference it from as many environments as you like, rather than repeating paths. |
| 53 | + |
| 54 | +### Inheritance |
| 55 | + |
| 56 | +Sources merge entry by entry, so an environment can override a single redirection while everything else it inherits stays put: |
| 57 | + |
| 58 | +```toml config-example |
| 59 | +[tool.hatch.sources] |
| 60 | +foo = "./packages/foo" |
| 61 | +bar = "./packages/bar" |
| 62 | + |
| 63 | +[tool.hatch.envs.test-upstream.sources] |
| 64 | +foo = { git = "https://github.com/example/foo", branch = "main" } |
| 65 | +``` |
| 66 | + |
| 67 | +Every environment here installs both packages from local checkouts, except `test-upstream`, which keeps the local `bar` but tracks upstream `foo`. |
| 68 | + |
| 69 | +### Checking your work |
| 70 | + |
| 71 | +Redirections that quietly do nothing are the failure mode worth guarding against, so [`hatch dep show sources`](../../cli/reference.md#hatch-dep-show) reports what each source targets and which dependencies of the active environment it actually redirects. A source matching no dependency is reported with a warning — which is usually how you find out you typed `httpx2` where you meant `httpx`. |
| 72 | + |
| 73 | +To prove your published metadata still resolves on its own, set `HATCH_NO_SOURCES` to disable every redirection: |
| 74 | + |
| 75 | +``` |
| 76 | +HATCH_NO_SOURCES=1 hatch env create |
| 77 | +``` |
| 78 | + |
| 79 | +That is a good thing to put in CI. |
| 80 | + |
| 81 | +A few deliberate boundaries: a dependency that already uses a [direct reference](../../config/dependency.md#direct-references) wins over a configured source, sources never apply to build requirements so that builds stay reproducible, and they do not influence the metadata of wheels produced by `hatch build`. |
| 82 | + |
| 83 | +## Building every workspace member |
| 84 | + |
| 85 | +[Workspaces](../../how-to/environment/workspace.md) arrived in v1.16.0, but releasing one still meant walking the members yourself. The [`build`](../../cli/reference.md#hatch-build) command now takes `--all`/`-a`: |
| 86 | + |
| 87 | +``` |
| 88 | +hatch build --all |
| 89 | +``` |
| 90 | + |
| 91 | +This builds an sdist and a wheel for the workspace root and for every member of the selected environment, consolidating the artifacts in the root's `dist` directory — ready to hand straight to `twine upload dist/*`. Pass a location to put them elsewhere: |
| 92 | + |
| 93 | +``` |
| 94 | +hatch build --all out/artifacts |
| 95 | +``` |
| 96 | + |
| 97 | +The root is built first and does not need to list itself as a member. If your top-level `pyproject.toml` has no `project` table and exists purely to hold workspace configuration, the root is skipped and only the members are built. |
| 98 | + |
| 99 | +## Fixes |
| 100 | + |
| 101 | +This release carries a larger-than-usual batch of fixes. |
| 102 | + |
| 103 | +**`hatch run` responds to Ctrl-C again.** Commands run through `hatch run` had become uninterruptible: the parent process ignored `SIGINT`, and the child inherited that. Interrupting a long test run works as it should now. |
| 104 | + |
| 105 | +**Free-threaded builds get free-threaded interpreters.** When Hatch itself runs on a free-threaded build and has to install a Python distribution, it was selecting a GIL-enabled one — silently changing the execution model of the environment it just created. It now selects the distribution matching the running interpreter, such as `3.14t`. The new selectors described below also reach environment configuration: `python = "3.14t"` was initially rejected there even though `hatch python install 3.14t` accepted it, and both paths now agree. |
| 106 | + |
| 107 | +**Prereleases are never selected automatically.** With Python 3.15 distributions now available (currently 3.15.0rc1), the fallback that picks the latest compatible version could have handed you a release candidate without asking. Automatic selection is restricted to stable releases; a prerelease still installs when you request one explicitly. |
| 108 | + |
| 109 | +**Type checking works on Windows.** The Pyrefly configuration Hatch generates for `hatch check types` embedded absolute paths containing backslashes, which TOML read as escape sequences, producing an invalid config. |
| 110 | + |
| 111 | +**Environment creation survives uninstalled metadata hooks.** Creating an environment crashed when the project configured a metadata hook that was not installed in the Hatch CLI's own environment. |
| 112 | + |
| 113 | +**Coverage data no longer leaks between runs.** `hatch test --cover` now erases stale coverage data before running, so results reflect the run in front of you. |
| 114 | + |
| 115 | +**No more hardcoded reliance on `pip`.** Internal dependency installation now goes through `uv`. |
| 116 | + |
| 117 | +## Also in this release |
| 118 | + |
| 119 | +- `tool.hatch.requires-hatch` — a version specifier set that commands reading your project's metadata enforce against the running version of Hatch, so a project that depends on newer behavior can say so. See [how to constrain Hatch](../../how-to/config/constrain-hatch.md). |
| 120 | +- `hatch version` can now bump a version that is statically defined by `project.version`, rewriting `pyproject.toml` in place instead of refusing. Pass `--force` to allow an explicit downgrade. |
| 121 | +- Free-threaded distribution names such as `3.13t` and `3.14t` are first-class in the `python` commands and the environment `python` option, rather than requiring `HATCH_PYTHON_VARIANT_GIL`. |
| 122 | +- Python 3.15 distributions are available to install, and the default CPython distributions have been upgraded to the 20260807 release. |
| 123 | + |
| 124 | +### Support |
| 125 | + |
| 126 | +If you or your organization finds value in what Hatch provides, consider sponsoring our maintainers [Ofek](https://github.com/sponsors/ofek) and [Cary](https://github.com/sponsors/cjames23) to assist with maintenance and more rapid development! |
0 commit comments