Add env lock command to generate PEP compliant lock files.

docs/config/environment/overview.md

@@ -290,6 +290,55 @@ The following platforms are supported:
 
 If unspecified, the environment is assumed to be compatible with all platforms.
 
+## Locking
+
+Hatch can generate [PEP 751](https://peps.python.org/pep-0751/) lockfiles (`pylock.toml`) for environments. Lockfiles capture the exact versions of all resolved dependencies, ensuring reproducible installations.
+
+### Locked
+
+Set `locked` to `true` to enable automatic lockfile generation for an environment. When enabled, a lockfile will be generated whenever the environment is created or its dependencies change.
+
+```toml config-example
+[tool.hatch.envs.test]
+locked = true
+dependencies = [
+  "pytest",
+  "pytest-cov",
+]
+```
+
+The default value is `false` unless overridden by the global [`lock-envs`](#lock-envs) setting.
+
+### Lock filename ### {: #lock-filename }
+
+By default, lockfiles are named following the [PEP 751](https://peps.python.org/pep-0751/) convention: `pylock.toml` for the `default` environment and `pylock.<ENV_NAME>.toml` for all others. You can override this with the `lock-filename` option:
+
+```toml config-example
+[tool.hatch.envs.test]
+lock-filename = "locks/test-requirements.lock"
+```
+
+### Global lock-envs ### {: #lock-envs }
+
+You can enable locking for all environments at once by setting `lock-envs` to `true` at the top level of your Hatch configuration:
+
+```toml config-example
+[tool.hatch]
+lock-envs = true
+```
+
+This acts as the default value for each environment's [`locked`](#locked) option. Individual environments can still opt out by explicitly setting `locked = false`:
+
+```toml config-example
+[tool.hatch]
+lock-envs = true
+
+[tool.hatch.envs.docs]
+locked = false
+```
+
+See the [lockfile how-to guide](../../how-to/environment/lockfiles.md) for practical usage examples.
+
 ## Description
 
 The `description` option is purely informational and is displayed in the output of the [`env show`](../../cli/reference.md#hatch-env-show) command:

docs/environment.md

@@ -95,6 +95,18 @@ Syncing dependencies
 !!! note
     The `Syncing dependencies` status will display temporarily when Hatch updates environments in response to any dependency changes that you make.
 
+## Locking
+
+Hatch can generate [PEP 751](https://peps.python.org/pep-0751/) lockfiles (`pylock.toml`) for environments. Configure environments with [`locked = true`](config/environment/overview.md#locked) and then use the [`env lock`](cli/reference.md#hatch-env-lock) command:
+
+```console
+$ hatch env lock
+Locking environment: default
+Wrote lockfile: /path/to/project/pylock.toml
+```
+
+When called without arguments, all environments configured with `locked = true` will be locked. Environments are also locked automatically when created or when their dependencies change. See the [lockfile how-to guide](how-to/environment/lockfiles.md) for more details.
+
 ## Selection
 
 You can select which environment to enter or run commands in by using the `-e`/`--env` [root option](cli/reference.md#hatch) or by setting the `HATCH_ENV` environment variable.

docs/history/hatch.md

@@ -8,6 +8,11 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 
 ## Unreleased
 
+***Added:***
+
+- Add `hatch env lock` command to generate [PEP 751](https://peps.python.org/pep-0751/) lockfiles (`pylock.toml`) for environments
+- Add `locked` per-environment setting and `lock-envs` global setting for automatic lockfile generation
+
 ## [1.16.3](https://github.com/pypa/hatch/releases/tag/hatch-v1.16.3) - 2026-01-20 ## {: #hatch-v1.16.3 }
 
 ***Added:***

docs/how-to/environment/lockfiles.md

@@ -0,0 +1,128 @@
+# How to use lockfiles
+
+-----
+
+Hatch can generate [PEP 751](https://peps.python.org/pep-0751/) lockfiles (`pylock.toml`) for your environments. Lockfiles capture the exact resolved versions and hashes of all dependencies, ensuring reproducible installations across machines and CI.
+
+## Configuring locked environments
+
+To use lockfiles, first configure which environments should be locked by setting [`locked = true`](../../config/environment/overview.md#locked):
+
+```toml config-example
+[tool.hatch.envs.test]
+locked = true
+dependencies = [
+  "pytest",
+]
+```
+
+Or enable it globally for all environments with the [`lock-envs`](../../config/environment/overview.md#lock-envs) setting:
+
+```toml config-example
+[tool.hatch]
+lock-envs = true
+```
+
+Individual environments can opt out:
+
+```toml config-example
+[tool.hatch]
+lock-envs = true
+
+[tool.hatch.envs.docs]
+locked = false
+```
+
+## Generating lockfiles
+
+Use the [`env lock`](../../cli/reference.md#hatch-env-lock) command to generate lockfiles. When called without arguments, it locks all environments configured with `locked = true`:
+
+```console
+$ hatch env lock
+Locking environment: default
+Wrote lockfile: /path/to/project/pylock.toml
+Locking environment: test
+Wrote lockfile: /path/to/project/pylock.test.toml
+```
+
+You can also lock a specific environment by name:
+
+```console
+$ hatch env lock test
+Locking environment: test
+Wrote lockfile: /path/to/project/pylock.test.toml
+```
+
+!!! note
+    When locking a specific environment by name, it must have `locked = true` configured. To generate a lockfile for an environment that is not configured as locked, use the `--export` flag.
+
+The `default` environment produces `pylock.toml`, while all other environments produce `pylock.<ENV_NAME>.toml`, following the [PEP 751](https://peps.python.org/pep-0751/) naming convention.
+
+## Automatic locking
+
+Environments with `locked = true` will have their lockfiles generated automatically during `hatch env create` or `hatch run` whenever:
+
+- The lockfile does not exist yet
+- The environment's dependencies have changed
+
+## Updating locked dependencies
+
+To upgrade all locked packages to their latest allowed versions:
+
+```console
+$ hatch env lock test --upgrade
+```
+
+To upgrade only specific packages:
+
+```console
+$ hatch env lock test --upgrade-package requests --upgrade-package urllib3
+```
+
+## Checking if a lockfile is up-to-date
+
+Use the `--check` flag to verify that a lockfile exists without regenerating it:
+
+```console
+$ hatch env lock test --check
+Lockfile exists: /path/to/project/pylock.test.toml
+```
+
+This is useful in CI to ensure lockfiles have been committed.
+
+## Exporting lockfiles
+
+To generate a lockfile for an environment that is not configured with `locked = true`, or to write to a custom location, use `--export`:
+
+```console
+$ hatch env lock default --export locks/default.lock
+```
+
+To export lockfiles for all environments into a directory, use `--export-all`:
+
+```console
+$ hatch env lock --export-all locks/
+```
+
+!!! note
+    `--export` and `--export-all` are mutually exclusive.
+
+## Custom lock filenames
+
+You can override the default filename for any environment with the [`lock-filename`](../../config/environment/overview.md#lock-filename) option:
+
+```toml config-example
+[tool.hatch.envs.test]
+lock-filename = "requirements-test.lock"
+```
+
+When multiple matrix environments share the same `lock-filename`, Hatch will merge their dependencies and generate the lockfile once.
+
+## Installer integration
+
+Lockfile generation delegates to whichever installer your environment is configured to use:
+
+- **pip** (default): Uses `pip lock` (requires pip 25.1+) to produce a `pylock.toml` file directly.
+- **UV**: Uses `uv pip compile` to resolve dependencies with hashes.
+
+See [How to select the installer](select-installer.md) for details on configuring UV.

mkdocs.yml

@@ -130,6 +130,7 @@ nav:
     - Environments:
       - Select installer: how-to/environment/select-installer.md
       - Dependency resolution: how-to/environment/dependency-resolution.md
+      - Lockfiles: how-to/environment/lockfiles.md
       - Workspace: how-to/environment/workspace.md
     - Static analysis:
       - Customize behavior: how-to/static-analysis/behavior.md

src/hatch/cli/env/__init__.py

@@ -2,6 +2,7 @@
 
 from hatch.cli.env.create import create
 from hatch.cli.env.find import find
+from hatch.cli.env.lock import lock
 from hatch.cli.env.prune import prune
 from hatch.cli.env.remove import remove
 from hatch.cli.env.run import run
@@ -15,6 +16,7 @@ def env():
 
 env.add_command(create)
 env.add_command(find)
+env.add_command(lock)
 env.add_command(prune)
 env.add_command(remove)
 env.add_command(run)