Skip to content

⚡ perf(startup): defer pathlib loading - #228

Merged
gaborbernat merged 1 commit into
mainfrom
perf/lazy-startup
Nov 18, 2026
Merged

gaborbernat merged 1 commit into
mainfrom
perf/lazy-startup

Conversation

@gaborbernat

@gaborbernat gaborbernat commented Nov 18, 2026 •

Copy link
Copy Markdown
Member

The pre-commit-uv startup hook runs when Python starts, including processes that never run pre-commit. On Python 3.15, a paired 60-run benchmark of interpreter startup fell from 11.8 to 10.1 ms and peak memory from 11.5 to 10.8 MiB. Python 3.14 showed no material change.

The startup hook still checks whether the process is running pre-commit. Processes that do not run pre-commit skip the environment health check, so they no longer load pathlib through this hook. Lifeguard found no lazy-import incompatibility in this module, and flake8-lazy identified pathlib as eligible.

Benchmarks

Each block is one paired 60-run hyperfine invocation with --warmup 5 --metrics time_wall_clock:ms,memory_peak_resident:MiB. Both commands used the same tox interpreter and dependencies, with PYTHONPATH selecting the merge-base or PR source tree. The direct module import uses -S to isolate the hook from site initialization; the startup workload uses normal site initialization and executes python -c pass.

Python 3.15

Interpreter startup with the .pth hook

Benchmark 1: Before (60 runs)
                mean     ±       σ          min     …     max
  Wall Time     11.8 ms  ±     1.1 ms      10.8 ms  …    16.9 ms
  Memory        11.5 MiB ±     0.0 MiB     11.4 MiB …    11.6 MiB
 
Benchmark 2: After (60 runs)
                mean     ±       σ          min     …     max
  Wall Time     10.1 ms  ±     0.6 ms       9.4 ms  …    12.1 ms           -14.2%
  Memory        10.8 MiB ±     0.0 MiB     10.6 MiB …    10.9 MiB           -6.5%

Direct hook import (python -S -c 'import pre_commit_uv._pre_commit_patch')

Benchmark 1: Before (60 runs)
                mean     ±       σ          min     …     max
  Wall Time     10.1 ms  ±     0.3 ms       9.8 ms  …    11.1 ms
  Memory        10.8 MiB ±     0.0 MiB     10.6 MiB …    10.9 MiB
 
Benchmark 2: After (60 runs)
                mean     ±       σ          min     …     max
  Wall Time      9.3 ms  ±     1.0 ms       8.5 ms  …    11.8 ms            -8.4%
  Memory        10.5 MiB ±     0.1 MiB     10.3 MiB …    10.6 MiB           -3.2%

Python 3.14

Interpreter startup with the .pth hook

Benchmark 1: Before (60 runs)
                mean     ±       σ          min     …     max
  Wall Time     12.9 ms  ±     0.7 ms      12.2 ms  …    15.1 ms
  Memory        13.6 MiB ±     0.1 MiB     13.4 MiB …    13.8 MiB
 
Benchmark 2: After (60 runs)
                mean     ±       σ          min     …     max
  Wall Time     13.1 ms  ±     1.6 ms      12.2 ms  …    17.7 ms            +1.9%
  Memory        13.6 MiB ±     0.1 MiB     13.4 MiB …    13.7 MiB           -0.2%

Direct hook import (python -S -c 'import pre_commit_uv._pre_commit_patch')

Benchmark 1: Before (60 runs)
                mean     ±       σ          min     …     max
  Wall Time     11.9 ms  ±     0.3 ms      11.5 ms  …    13.6 ms
  Memory        13.4 MiB ±     0.1 MiB     13.3 MiB …    13.6 MiB
 
Benchmark 2: After (60 runs)
                mean     ±       σ          min     …     max
  Wall Time     12.1 ms  ±     0.3 ms      11.6 ms  …    12.9 ms            +1.6%
  Memory        13.4 MiB ±     0.1 MiB     13.3 MiB …    13.6 MiB           +0.1%

Import profile

These Python 3.15 diagrams come from python -X importtime -c pass and tuna. pathlib appears in the startup hook's import tree before the change and is absent afterward.

Before

Before startup import tree

After

After startup import tree

@gaborbernat gaborbernat added the enhancement New feature or request label Nov 18, 2026
@gaborbernat
gaborbernat marked this pull request as ready for review November 18, 2026 22:29
@gaborbernat
gaborbernat merged commit dd8f8d4 into main Nov 18, 2026
20 checks passed
@gaborbernat
gaborbernat deleted the perf/lazy-startup branch November 18, 2026 23:11
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant