DEV Community: Menshikov Vasil

How I Cut Python Docker Image Size From 1.2 GB to a Lean, Secure Container

Menshikov Vasil — Tue, 04 Aug 2026 08:24:46 +0000

When we moved our tracking API to Kubernetes, the container turned out to be the weakest link in the whole thing. It was a 1.2 GB image that took two full minutes to rebuild on every code change and then, adding insult to injury, flat-out refused to run in our local k3d cluster. If you've ever wanted to reduce a Python Docker image size and wondered why your "working" image won't load into a cluster, this is the afternoon where I fixed all three problems at once - and stopped being quietly embarrassed by my own Dockerfile.

Why this bugged me for weeks

Our service, myapp, is a Python 3.12 and FastAPI HTTP API on port 8080 that talks to PostgreSQL. The first Dockerfile I ever wrote for it is the first Dockerfile anyone writes, and it technically works:

FROM python:3.12
WORKDIR /code
COPY . .
RUN pip install -r requirements.txt
CMD python -m uvicorn app.main:app --host 0.0.0.0 --port 8080

Here's the uncomfortable truth: every single line is a small mistake. The full-fat python:3.12 base is enormous. COPY . . before pip install means a one-character code edit invalidates the dependency layer and reinstalls the world. The shell-form CMD quietly breaks signal handling. And it runs as root. I lived with all of this for longer than I'd like to admit, treating the slow rebuilds as just the cost of doing business, until I got fed up and went hunting for a canonical, production-minded reference. Someone had written up a walkthrough on writing a small, fast, secure Dockerfile for a FastAPI service and loading it into k3d, and honestly it restructured how I think about every instruction in the file.

The cheapest 90% win: fix your layer order

Each Dockerfile instruction is a layer, Docker caches them, and - this is the part that matters - if a layer changes, every layer after it is invalidated too. I was editing application code dozens of times a day and almost never touching dependencies, yet my ordering forced a full pip install on every build. The fix is embarrassingly simple: install what rarely changes before copying what changes constantly.

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt   # heavy, rarely changes
COPY ./app ./app                                      # light, changes often

That one reorder dropped my rebuild from around two minutes to a few seconds on a code-only change, because the dependency layer now comes straight from cache. It's the single most common Dockerfile anti-pattern in existence, and I'd been cheerfully living inside it for months.

The multi-stage build

The naive image ships everything into the final result - compilers, dev headers, pip caches - all of it dead weight at runtime. A multi-stage build installs dependencies in a build stage and copies only the finished virtualenv into a clean runtime image:

# --- Stage 1: build ---
FROM python:3.12-slim AS build
ENV PYTHONDONTWRITEBYTECODE=1 PYTHONUNBUFFERED=1 PIP_NO_CACHE_DIR=1
WORKDIR /code
RUN python -m venv /opt/venv
ENV PATH="/opt/venv/bin:$PATH"
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# --- Stage 2: runtime ---
FROM python:3.12-slim
ENV PYTHONDONTWRITEBYTECODE=1 PYTHONUNBUFFERED=1 PATH="/opt/venv/bin:$PATH"
WORKDIR /code
COPY --from=build /opt/venv /opt/venv
COPY ./app ./app
EXPOSE 8080
CMD ["fastapi", "run", "app/main.py", "--port", "8080"]

How much you save depends entirely on your dependencies - with pure wheels the gain is modest, but we had a couple of packages that compiled from source, and dropping the build toolchain shrank the image substantially. Switching from python:3.12 to python:3.12-slim did the rest.

The small details that make it production-grade

The write-up drilled a handful of these in, and every one of them has bitten someone I know. Use fastapi run, not a bare uvicorn --reload - the reload flag is dev-only overhead in a cluster image, and FastAPI's own container guide uses fastapi run, which starts Uvicorn with sane production settings. Write CMD in exec form, as an array, so the app becomes PID 1 and receives SIGTERM from Kubernetes directly and shuts down gracefully; shell form wraps it in /bin/sh, the signal never arrives, and the Pod gets hard-killed on timeout. Set PYTHONUNBUFFERED=1, or your logs get stuck in a buffer and never surface in kubectl logs - I lost an hour to "why is my container silent" before I understood that one. Add an unprivileged user with adduser --disabled-password --uid 10001 appuser and then USER appuser, because root-by-default violates least privilege and it pairs later with securityContext.runAsNonRoot: true in the manifest. And add a .dockerignore, because without one I was shipping .git, a local .venv, and nearly a .env straight into the build context.

The bug that stole a full day: ImagePullBackOff

With a beautiful new image built, I ran docker build, applied the manifest, and the Pod sat in ImagePullBackOff forever. It seems completely obvious that a freshly built local image would be visible to the cluster. It is not, and this cost me a full day of my life. k3d nodes run their own containerd, isolated from your Docker daemon - an image sitting in Docker is invisible to the cluster, and the kubelet just keeps failing to pull it from a remote registry that doesn't have it.

The fastest fix for a one-off test is a direct import:

docker build -t myapp:dev .
k3d image import myapp:dev -c dev

Pair that with imagePullPolicy: IfNotPresent in the manifest so Kubernetes doesn't reach for the network anyway. For ongoing work we moved to k3d's built-in registry, where the same name k3d-registry.localhost:5000/myapp:dev works for both push from the host and pull from inside the cluster. The full delivery model - both paths, plus why *.localhost resolves - is covered in the companion write-up linked in Sources below.

Two more touches that paid off

First, a HEALTHCHECK that doesn't need curl. I wanted Docker to know whether the service was alive during local runs, but python:3.12-slim has no curl, and neither does distroless. So I did the check with Python, which is guaranteed to be in the image:

HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \
  CMD ["python", "-c", "import urllib.request,sys; sys.exit(0 if urllib.request.urlopen('http://localhost:8080/healthz').getcode()==200 else 1)"]

Second, actually understanding what EXPOSE does and doesn't do. For an embarrassingly long time I thought EXPOSE 8080 published the port. It doesn't - the Dockerfile reference is explicit that EXPOSE doesn't actually publish anything; it's pure metadata, documentation for whoever reads the file. Real publishing happens with -p in docker run, or with Service and Ingress objects in Kubernetes. Internalizing that killed a whole afternoon of "why can't I reach the port" confusion, purely because I stopped expecting EXPOSE to do a job it was never designed for.

I also standardized on running a single worker per Pod and scaling with replicas, rather than cramming Gunicorn plus multiple Uvicorn workers into one container. In Kubernetes the cluster is the process manager, and letting it own concurrency kept my image simpler and my resource limits meaningful. For local development it's not even a question - one process is plenty.

How it feels now

The difference is night and day, and it's satisfying in a way that's hard to overstate. The base went from the full python:3.12 to a multi-stage python:3.12-slim. A rebuild on a code change went from roughly two minutes of full pip install to a few seconds served from cache. The container runs as uid 10001 appuser instead of root. Signal handling went from broken - the shell-form CMD swallowing SIGTERM - to correct, with the app as PID 1 receiving signals directly. And the image, which used to greet me with ImagePullBackOff every time, now imports and pushes into k3d cleanly.

For local dev I deliberately stayed on slim, because it's genuinely easy to debug. When I hardened the image for production later, I moved the runtime to distroless (gcr.io/distroless/python3-debian12) - no shell, no package manager, far fewer CVEs - building the deps on slim and copying them across. The trade-off is real: docker exec ... sh no longer works, so you debug with kubectl debug and ephemeral containers instead. That's a fair price for the reduced attack surface, but it's a choice worth making consciously rather than by accident.

What stuck with me most is how tangled up all of this had felt when it was really one thing. I'd been treating "make it smaller," "make it faster," "make it secure," and "make it actually run in the cluster" as four separate chores I'd get to someday. They were never four projects. They were one Dockerfile, done with a little more care than the copy-paste version I'd been shrugging past for months - and the version of me who kept restarting slow builds would not believe how good a well-ordered Dockerfile feels to live with.

Sources & further reading

Docker docs — Multi-stage builds
Docker docs — Optimizing builds with cache (layer invalidation)
Docker docs — Dockerfile reference: EXPOSE and CMD exec form
GoogleContainerTools/distroless — Minimal images with no shell or package manager
FastAPI docs — FastAPI in Containers - Docker
A local-Kubernetes containerization write-up someone put together, with the complete annotated Dockerfile and the slim-vs-alpine-vs-distroless decision

How a Test Coverage Ratchet Finally Fixed the Codebase Everyone Was Afraid to Touch

Menshikov Vasil — Mon, 03 Aug 2026 09:25:03 +0000

I have never seen a metric sit as stubbornly still as our test coverage did. Twenty-five percent. For two years. It wasn't drifting up, it wasn't drifting down, it just sat there like furniture nobody wanted to move. And the thing that eventually fixed it wasn't a rewrite or a hero week - it was a small, almost boring idea called a test coverage ratchet, which I'll get to. First I want to tell you why this bugged me for so long, because the psychology turned out to matter more than the config.

Why this bugged me for years

I joined a team maintaining a ~400,000-line JavaScript and TypeScript monolith. Coverage was 25% and everyone knew it. It's not that people didn't care - I watched them care, out loud, in retros. It's that every attempt to fix it failed the exact same way. Someone would pitch a "refactoring sprint," leadership would grudgingly hand over two weeks, the team would rewrite one module, a production incident would eat half the time, and the whole thing would quietly evaporate. Coverage: still 25%.

What really got under my skin was watching genuinely excellent engineers make a one-line change to a function they clearly understood, and then refuse to clean up the obvious mess sitting right next to it. When I asked why, the answers were always the same flavor: "it's always worked this way," "better not touch it," "honestly it'd be easier to rewrite than to understand." That's not laziness. Once I stopped reading it as laziness, everything reframed.

The thing I finally understood: it's fear, not incompetence

Teams don't rot from a lack of knowledge. They rot from fear. When a codebase is big and fragile, every change feels dangerous, so people start programming defensively - the smallest possible edit, a workaround instead of a fix. And it feeds on itself: the worse the code gets, the less anyone wants to touch it, which makes it worse. Psychologists have a name for it, learned helplessness, that state where you stop trying to change a situation even when you actually could. Michael Feathers puts the technical half of it bluntly in Working Effectively with Legacy Code - "legacy code is simply code without tests" - which is exactly why the fear is rational. With no tests, every edit really is a gamble.

And here's the thing that clicked for me: you cannot fix learned helplessness with a two-week sprint. A sprint says "all or nothing," and since "all" is impossible, the brain quietly hears "nothing." The way out is the opposite of a sprint - tiny, achievable, basically-guaranteed-to-succeed steps. That's the whole spirit of incremental constraints, and it lines up perfectly with Robert C. Martin's Boy Scout Rule: leave every file you touch a little better than you found it. Not perfect. A little better. Rename one variable, split one bloated function, delete one bit of duplication.

The rule we actually wrote down

We put one sentence on the team wiki: every change should leave the code in a better state than before the change. Then we made it concrete. New files had to meet a real bar - tests for public methods, no exceptions. Modified files couldn't lose coverage, and ideally gained a few points. Critical bug fixes shipped with a regression test that reproduced the bug. Refactors shipped with a test proving behavior hadn't changed.

The magic is entirely in the asymmetry. We never asked anyone to go improve the 300,000 lines of legacy code. We asked only that whatever you newly wrote or happened to touch that day met the bar. Legacy code you never open never blocks you. That one boundary is what made the whole thing feel possible instead of doomed.

Making it real: the ratchet lives in CI

A rule nobody enforces is just a nice feeling on a wiki. So we encoded the ratchet in three layers.

The first is a two-tier jest coverage threshold. The trick is a per-path override - jest's coverageThreshold takes both a global block and path/glob-specific blocks, and a glob's files are held to their own bar independently of the global one. We pinned the global numbers at today's levels so they could never slide backward, while new feature directories answered to 80%:

// jest.config.js
module.exports = {
  collectCoverageFrom: ['src/**/*.{js,ts,tsx}'],
  coverageThreshold: {
    global: {
      branches: 25, // current level - never decrease
      functions: 30,
      lines: 35,
      statements: 35
    },
    // Everything created after we flipped the switch
    'src/features/**/*.ts': {
      branches: 70,
      functions: 80,
      lines: 80,
      statements: 80
    }
  }
}

Every few weeks, once the global numbers had drifted upward on their own, we'd bump the global floor up to meet them. That's the whole idea of a ratchet - it only ever clicks in one direction, and it can't click back.

The second layer is a quality gate that judges only the diff. This pattern has a name too: diff coverage, sometimes called patch coverage. You hold a high bar only to the lines a pull request adds or changes, and you cheerfully ignore the legacy sea around them. Codecov ships this as a first-class check - its codecov/patch status "only measures lines adjusted in the pull request" - so you can demand 80% on new lines without touching the rest of the repo. Ready-made ratchet tools exist as well; jest-coverage-ratchet reads your coverage summary and nudges each threshold up to the current level so it can only ever go higher. All of these are lovely. But a tool with no culture behind it just becomes another gate people learn to game, so we wrote a thin wrapper of our own to keep the numbers legible to the team:

# .github/workflows/quality-gate.yml
name: Quality Gate
on: [pull_request]
jobs:
  quality-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
        with:
          fetch-depth: 0  # needed for diff analysis
      - name: Check coverage for changed files
        run: |
          CHANGED_FILES=$(git diff --name-only origin/main...HEAD | grep -E '\.(js|ts|tsx)$')
          if [ ! -z "$CHANGED_FILES" ]; then
            npm run test:coverage
          fi

We rolled it out with a phase I'd call "measurement without judgment" - run coverage, ESLint, and duplication analysis purely to see where we stood, with zero blame attached to any number. That framing mattered enormously. Nobody feels attacked by a dashboard they helped set up.

The third layer is ESLint with the same asymmetry - strict complexity limits on new directories, warnings-only on the legacy ones, so src/features/** answered to a complexity ceiling of 8 and 30-line functions, while src/legacy/** got gentle warnings at 15 and 100. Same shape, different tool.

The trick that unlocked the genuinely scary files

Some functions were terrifying - a 200-line calculateDiscount nobody fully understood. You can't refactor what you can't describe, and this is where Feathers' characterization test earns its keep: it "characterizes the actual behavior of a piece of code". You don't test what the code should do. You test what it currently does, whatever that is, warts and all, and pin it in place before you dare touch anything:

describe('calculateDiscount - current behavior', () => {
  it('VIP user with promo XYZ123', () => {
    const result = calculateDiscount({ type: 'VIP' }, [{ price: 100 }], 'XYZ123');
    // We don't know WHY it's 0.25, we're just pinning current behavior
    expect(result.discount).toBe(0.25);
  });
});

The emotional shift here is real. Once a tangled function is wrapped in characterization tests, it just stops being scary. You've got a net that screams the instant behavior changes, so you can finally carve it into small, testable pieces with your shoulders down.

How it feels now

Eleven months later, global line coverage had climbed from 25% to 61%, and the code we shipped that quarter was sitting around 84% - up from maybe 10% before. We reverted far fewer PRs for regressions, and "safe-ing" a scary legacy function went from a thing we simply avoided to something you could knock out in an afternoon. Most tellingly, the number of engineers willing to touch calculateDiscount went from exactly one to most of the team.

But the number I care about most is the one we never scheduled: zero dedicated refactoring sprints. Coverage climbed because ordinary feature work now dragged quality up with it, one touched file at a time, and nobody had to be a hero.

We hit a few walls worth naming. Don't set the new-code bar at 100% - we tried 90% and people gamed it with trivial assertions; 80% forced real tests without inviting malicious compliance. Bump the global floor by hand, in its own PR, on purpose - we automated it once and a hot-fix that happened to touch a well-covered file caused flaky failures. And treat "measurement without judgment" as load-bearing: the first time a manager used the coverage dashboard to single someone out in a review, trust cratered for a month. Kill that instinct early and loudly.

If you want the long version - the full psychology, every config, the pre-commit hooks I didn't have room for - someone wrote up the whole incremental-constraints playbook here, and it's worth a read before you pitch your next doomed sprint.

What stays with me isn't the graph. It's that "better not touch it" has basically vanished from our standups. We didn't make anyone braver by asking them to be brave. We just made the next small step safe enough that bravery stopped being the requirement - and it turns out an entire team quietly leaving files a little better than they found them will outrun any refactoring sprint you could ever schedule.

Sources & further reading

The brew services Setup That Finally Got Docker Desktop Off My Mac (and Made Local Postgres Feel Instant)

Menshikov Vasil — Sun, 02 Aug 2026 08:39:15 +0000

For a long time the first fifteen minutes of my workday belonged to a whale. I'd open the laptop, hear the fans spin up, watch "Docker Desktop is updating," and wait - all so I could run a single local Postgres container that my Mac was perfectly capable of running on its own. The morning three people on my team showed up late to standup for the exact same reason ("my fans won't stop and Postgres won't bind," "I ran docker compose up and my battery's already at 40%"), something in me finally snapped. This is the brew services setup that got Docker Desktop off our machines, and honestly, made local development feel joyful again.

Why this bugged me for years

Our local stack was not exotic. One docker-compose.yml with Postgres, Redis, and MySQL. That's it. And yet Docker Desktop's VM taxed every machine the entire day - idle RAM I could feel, CPU burned on file-sync I never asked for, a licensing question hanging over the whole thing, and that update nag that always seemed to block me at the worst possible moment.

The licensing part had teeth, too. Under the Docker Subscription Service Agreement, Docker Desktop needs a paid subscription once your company is big enough - the free tier caps out under 250 employees and $10M revenue. We were over one of those lines, which meant Docker Desktop wasn't only a performance tax, it was a per-seat bill for the privilege of running one Postgres. That combination gnawed at me for a genuinely embarrassing amount of time before I did anything about it.

What finally reframed it was saying the obvious thing out loud: on a Mac, you already own a first-class service supervisor. It's called launchd, it's what Apple uses to run its own daemons, and Homebrew speaks it fluently. I'd been renting a Linux VM to babysit a database my operating system already knew how to babysit.

Why brew services instead of a container

The pitch is almost too simple. Homebrew installs Postgres, Redis, MySQL, MongoDB, Nginx, RabbitMQ, Elasticsearch, Kafka - the whole cast of local dev dependencies - as native formulae. Then brew services wraps macOS's own launchd so those processes start at login, get supervised, and stop cleanly (the full command surface lives in the Homebrew manpage). No VM. No file-sync layer. No 4GB toll booth in front of a single database.

I want to be honest about the trade-off, because I treated this as a decision and not a religion. Containers give you isolation, reproducibility, multiple versions side by side, and real production parity. Homebrew gives you native performance, near-zero overhead, and a Mac-first experience for the ninety-percent case where you just need a Postgres to develop against. Both of those are true at once. If you want the longer version of that decision, with all the commands and the honest tradeoffs laid out, someone wrote up the whole Homebrew-vs-containers case here and it's a good companion read.

And yes, I did the responsible thing and evaluated the usual Docker Desktop alternatives first. Colima, OrbStack, and Podman are all genuinely lighter than Docker Desktop and worth knowing - Colima especially gives you a Docker-compatible runtime with minimal fuss. But they're still containers. They shave the licensing and some of the RAM; they don't change the fundamental fact that you're running a Linux VM to host a database your Mac can run natively. For a single local Postgres or Redis, brew services isn't a lighter container runtime. It's no container at all - which is the part most "Docker Desktop alternatives 2025" roundups quietly skip.

The setup: four commands and a launchd file

Here's the entire day-to-day surface. Four commands:

# Start a service
brew services start postgresql

# Stop a service
brew services stop postgresql

# Restart a service
brew services restart postgresql

# List all services and their status
brew services list

That last one is the command I actually live in. It hands you an at-a-glance view of what's running and where its config lives:

$ brew services list
Name       Status  User    Plist
mysql      started username /Users/username/Library/LaunchAgents/homebrew.mxcl.mysql.plist
postgresql stopped
redis      started username /Users/username/Library/LaunchAgents/homebrew.mxcl.redis.plist

Our old onboarding doc had a two-page section titled "Installing and troubleshooting Docker Desktop." The new version is a shell snippet:

brew install postgresql@16 redis mysql
brew services start postgresql@16
brew services start redis
brew services start mysql

A new hire now goes from a fresh laptop to a working database stack in about the time it takes to fetch coffee. No account, no login, no license-acceptance dialog. The first time I watched someone new run that snippet and just... have a database, I felt a little pang about all the mornings I'd lost to the whale.

What's actually happening underneath

I didn't want to hand anyone a magic command they couldn't reason about, so we documented the mechanism. When you run brew services start postgresql, Homebrew generates and registers a .plist with launchd - the same supervision layer Apple uses for system daemons. Apple's Technical Note TN2083 on Daemons and Agents is the canonical reference for how login agents like this get loaded, and thoughtbot's walkthrough of starting and stopping services with Homebrew is a friendly plain-English companion. The generated plist is refreshingly readable:

<?xml version="1.0" encoding="UTF-8"?>
<plist version="1.0">
<dict>
  <key>Label</key>
  <string>homebrew.mxcl.postgresql</string>
  <key>ProgramArguments</key>
  <array>
    <string>/usr/local/opt/postgresql/bin/postgres</string>
    <string>-D</string>
    <string>/usr/local/var/postgres</string>
  </array>
  <key>RunAtLoad</key>
  <true/>
  <key>KeepAlive</key>
  <true/>
  <key>StandardErrorPath</key>
  <string>/usr/local/var/log/postgres.log</string>
</dict>
</plist>

RunAtLoad starts it at login. KeepAlive restarts it if it dies. Logs land at a predictable path you can just tail. Once people saw that this was only launchd doing what it already does for the whole OS, the "but is it reliable?" worries quietly dissolved.

How it feels now

I'm not going to pretend "trust me, it feels faster" is data, so we did measure it across a handful of volunteer machines for a couple of weeks. The headline is the memory. The local database stack went from something like 4GB of idle RAM under Docker Desktop to under 200MB with brew services - and getting roughly 4GB back on a 16GB MacBook is the difference between a laggy editor and a responsive one. Two people told me they'd stopped closing their browser to "make room" for the dev stack, which tells you everything about the world we'd been living in.

The rest followed. Cold database start dropped from nearly half a minute to under two seconds. The fans, which used to be a constant background hum, became a rare event. Onboarding went from around fourteen steps to four. And the annual license-management chore simply vanished. None of these numbers are exotic; they're just what happens when you stop running a VM to do a job your OS does natively.

The gotchas nobody puts in the README

It wasn't frictionless, and I'd be lying if I pretended otherwise. Version pinning is now on you - a container pins its version in the compose file, but Homebrew installs a version and a stray brew upgrade can move it out from under you mid-sprint. We standardized on the versioned formula, postgresql@16, and left a note in the Brewfile so nobody accidentally jumps a major version.

A service that "won't start" is almost always a stale socket or a log you haven't read yet. My debugging loop is boring and reliable: glance at brew services list, then actually read the log, then poke the service itself rather than trusting the status column.

brew services list
tail -f /usr/local/var/log/postgres.log
ps aux | grep postgres
launchctl list | grep postgres

Nine times out of ten the log names the culprit outright - a leftover postmaster.pid, a port already bound, a data dir from an older major version.

The sudo brew services trap is worth calling out too. Running a service as your user (a login agent) versus as root (a system daemon) puts the plist in different directories and changes when it starts; TN2083 above explains exactly why. For local dev you almost always want the user-level agent. We deleted one sudo somebody had copy-pasted from a random blog and half of our "it doesn't start at boot" complaints evaporated. And finally: your data now lives on the host with no volume abstraction, which is simpler but means a careless brew uninstall can take your local data with it. Our rule became a one-liner - your local DB is disposable, seed it from a script, never keep anything you can't regenerate.

Where Docker still wins, and why I kept it

I did not declare war on Docker. I just retired Docker Desktop as the default local-database runtime. The instant you need several services wired together for an integration test, or byte-for-byte production parity, containers are still exactly right. Our whole policy collapsed into one sentence: Homebrew for quick local databases, Docker for multi-service integration tests. Both live in the repo; you reach for the lighter one by default. That single sentence ended months of "should we standardize on containers or not" bikeshedding, because it was never either/or - most jobs are just lighter than we'd assumed.

We're tightening a couple of loose ends now, mostly a checked-in Brewfile so brew bundle reproduces the exact service set - and because Homebrew Bundle can start services declaratively with restart_service: true, that closes most of the reproducibility gap containers otherwise own.

What stays with me, though, isn't the RAM graph. It's that my laptop is quiet in the morning now. There's a particular kind of craft in noticing the tool you've been tolerating for years and asking whether it's actually earning its keep - and if your machine sounds like a jet engine every morning to run one Postgres and a Redis, I'd gently suggest it isn't.

Sources & further reading

How to Generate requirements.txt From What Your Code Actually Imports (pipreqs vs pip freeze)

Menshikov Vasil — Sat, 01 Aug 2026 16:15:03 +0000

There's a file in most Python projects that everyone commits and nobody reads, and for two years ours was quietly lying to us. If you've ever wondered how to generate a requirements.txt that reflects what your code actually needs - rather than every stray package that ever wandered into your virtualenv - this is the story of how I finally stopped trusting pip freeze for that job and switched to pipreqs. Our file went from 214 packages to 23, and honestly the bigger relief was emotional: I could finally open it and believe what it told me.

Why this bugged me for years

Every Python engineer knows the ritual. Finish a feature, run pip freeze > requirements.txt, commit, move on. It works. Right up until it doesn't.

Ours had metastasized. A new hire opened a PR and asked the most innocent question in code review: "Why does this API service depend on jupyter, matplotlib, and black?" It didn't. Those were tools somebody had pip install-ed into the shared venv months earlier and never removed. And pip freeze does not care in the slightest what your code imports - it snapshots everything installed in the environment. Our so-called source of truth was 90% noise, and I'd been squinting past it for so long I'd stopped seeing it.

That noise was not harmless, which is what finally pushed me to act. Docker builds crawled, because all 214 packages got resolved and installed on every cold build. Our vulnerability scanner shrieked about CVEs in libraries we never once imported. And worst of all, nobody could tell which dependencies were real, so nobody dared delete any of them. That last one is the quiet killer - a file so untrustworthy that fear freezes it in place. (I've watched the exact same fear freeze legacy test suites, so I recognized the smell immediately.)

So I went looking for a better way to generate the thing, and the tool I'd criminally underused was pipreqs, whose one-line pitch in its GitHub README is to "generate pip requirements.txt file based on imports of any project" - the exact opposite of what pip freeze does.

In fairness to pip freeze

I don't want to trash pip freeze, because it isn't wrong - it's just answering a different question than I was asking. The official pip docs are refreshingly blunt about this: it "reports what is installed; it does not compute a lockfile or a solver result." It answers "what is installed here," not "what does this code need." In a pristine, single-purpose virtualenv those two sets are identical. In a real, long-lived dev environment they drift apart embarrassingly fast.

The canonical flow is exactly what you'd expect:

# macOS/Linux
source venv/bin/activate
pip freeze > requirements.txt

If your venv is clean and dedicated to one project, that's genuinely the right tool - it captures exact versions of everything, which is precisely what you want for a fully reproducible environment. Our problem was simply that our venv had become a junk drawer, and we'd been using a drawer-inventory tool to describe a shopping list.

The thing that finally clicked

pipreqs takes the opposite approach, and once I understood it I felt a little silly for not switching sooner. It statically parses your .py files, finds the actual import statements, maps them to PyPI packages, and writes only those. Here's the whole sequence:

# 1. install it (once)
pip install pipreqs

# 2. from the project root, scan the code
cd /path/to/your/project
pipreqs .

# 3. regenerating over an existing file? force it
pipreqs . --force

The . is just the current directory - pipreqs walks it, reads the imports, and emits a requirements.txt containing only the libraries your code truly touches. The README documents the flags worth knowing: --savepath to write elsewhere, --print to dump to stdout, and --diff to compare an existing file against the project's real imports. That's the entire change. The generated file went from 214 lines to 23 - the same 23 packages the app had been importing all along, now finally the only 23 in the file.

The payoff rippled outward faster than I expected. The final Docker image roughly halved, dropping from around 1.3 GB to a little over 600 MB. A cold pip install in CI went from nearly three minutes to under a minute. Our scanner's findings on dependencies fell from thirty-one to six, and every one of those six was now a package we actually used, which meant we could actually triage them. And for the first time, "can I delete this dependency?" became a question with an answer instead of a shrug.

Where pipreqs bites (because it's not a silver bullet)

I'd be a bad engineer if I sold you pipreqs as pure upside, so here's where it drew blood - and the first one is a well-known limit of static analysis, not a bug. Dynamic and conditional imports simply get missed. If you reach for importlib.import_module(name) or import inside a try/except, pipreqs never sees it. We had exactly one - a plugin loaded by string name - and it broke at runtime until we pinned it by hand.

The other traps are gentler. Import name isn't always package name: import cv2 is really opencv-python, import yaml is PyYAML. pipreqs handles most of these through its mapping, but verify anything exotic. It infers versions from your environment or PyPI, so keep running it inside your activated venv to get versions that match what you actually tested against. And test/dev-only tools legitimately vanish from the output - which is the point, not a defect. If you want pytest and black tracked, give them their own requirements-dev.txt rather than mourning that pipreqs dropped them.

Our pragmatic landing spot: pipreqs generates the runtime requirements.txt, a hand-maintained requirements-dev.txt holds the tooling, and CI diffs the generated file to catch drift.

Rolling it out across twelve services without a big-bang

I'm allergic to regenerating every manifest in one heroic PR and praying, because bloated dependency files are load-bearing in ways you only discover when something 404s in prod at 2am. So we staged it. For each service we first saved the old pip freeze output as requirements.legacy.txt, so if pipreqs missed something we had the full list to diff against. Then we generated into a separate file with pipreqs . --force --savepath requirements.pipreqs.txt and reviewed what fell out by hand - ninety percent of the drops were obviously dev tooling, and the remaining ten percent got a human look. We rebuilt each image in a scratch container and ran the full suite plus a smoke test against the real boot path, not just unit tests, specifically to flush out the dynamic-import failures early. Then we promoted one service, let it bake in production for a week, and only then fanned out to the rest.

Exactly one service broke, and it broke exactly where I'd feared: our notification worker loads channel plugins by string name via importlib, so pipreqs never saw slack_sdk or twilio. The scratch-container smoke test caught it before any customer did. We dropped those two into an explicit requirements.extra.txt and concatenated it during the build. Cheap lesson, caught in the right place.

The reproducibility question everyone asks

The most common objection I heard internally was fair: "pip freeze guarantees exact versions and full transitive pinning - pipreqs only gives me top-level packages, isn't that less reproducible?"

The honest answer is that the two tools solve different halves of the problem, and the Python community has since standardized that split. pip freeze output plays the role of a lockfile - the exact, fully-resolved state you deploy. As of PEP 751 and the pylock.toml spec, a lockfile's entire job is "specifying dependencies to enable reproducible installation," pinning exact versions, URLs, and hashes. pipreqs shines as the other half - a manifest, the human-readable statement of intent about what your code needs. Our whole mistake had been asking one file to do both jobs, and letting the lockfile role bloat the manifest into something unreadable. If you want the long version of that manifest-versus-lockfile distinction and the staged rollout, someone wrote up the whole twelve-service migration here and it's a good deep-dive.

Our fix keeps both files: pipreqs writes the intent-level requirements.txt, and we resolve and pin into a separate lockfile at build time. The manifest is readable and reviewable again, and reproducibility lives where it belongs. We wired a guard into CI too - regenerate the file, and fail the build if it drifts from what's committed:

pipreqs . --force --savepath /tmp/req.check
diff <(sort requirements.txt) <(sort /tmp/req.check)

If a new import lands without updating the manifest, the diff is non-empty and the pipeline goes red. No more mystery dependencies sneaking in - or, more to the point, lingering unnoticed for two years.

How it feels now

We're piloting uv, Astral's Rust-based package manager, and weighing whether pyproject.toml should become the single source of dependency truth with requirements.txt generated as a lockfile artifact - which is where most modern Python workflows are clearly heading. But I keep coming back to how small the actual fix was. One tool swap turned a 214-line liability into a 23-line file that documents exactly what the service needs, and that's it.

What I didn't expect was the feeling. That file stopped being a place packages go to die and became something I actually read in review. If yours has that same graveyard smell, run pipreqs . against your project right now and diff it against what's committed. I'd bet you'll be a little startled - and maybe a little relieved - at how little your code actually imports.

Sources & further reading

pipreqs — the tool itself, README and flags (--savepath, --print, --diff, --force)
pip freeze — official pip documentation ("reports what is installed; it does not compute a lockfile")
PEP 751 / pylock.toml specification — the standardized lockfile format, Python Packaging User Guide
Writing your pyproject.toml — Python Packaging User Guide
uv — Astral's fast package/project manager with universal lockfiles
A full write-up of this migration someone put together — the staged rollout across twelve services, the CI drift check, and the manifest-vs-lockfile split

Hacker News + dev.to (thought-leadership framing of the inner-loop problem drives the whole funnel)

Menshikov Vasil — Wed, 22 Jul 2026 08:48:27 +0000

The Kubernetes inner dev loop is slow AND lies to you — here's why

If you've ever shipped a service to Kubernetes for the first time, you know the feeling: the edit→result loop that took a fraction of a second with uvicorn --reload suddenly takes 2–5 minutes, and code that "worked locally" dies in the cluster for reasons you never had to think about.

This is the opener of a new series on local Kubernetes development. It's a mental-model piece, not a tutorial — the goal is to name the two distinct problems most people blur together.

Key takeaways

The inner loop is the loop you crank dozens of times an hour: edit → build → run → check → fix, before you ever git push. Keeping it in the seconds is what protects your flow.
Kubernetes wedges four extra steps into that loop: docker build, update manifest, docker push, apply and wait for the Pod. That's the 2–5 min/iteration tax — vs ~1–5 s with file-sync/hot-reload (a 95%+ reduction).
The local cluster can't see images in your local Docker daemon. Skip the push/import step and you get a Pod stuck in ImagePullBackOff.
The :latest trap: myapp:latest defaults to imagePullPolicy: Always, so the kubelet re-pulls every start. Use specific tags + IfNotPresent.
Low fidelity is the other half of the pain: OOMKilled, CPU throttling, NetworkPolicy blocks, readiness failures, RBAC denials — a whole class of bugs invisible under bare uvicorn or docker compose.
Reframe shift-left as environment fidelity. As Testkube puts it: "testing earlier in a CI container that doesn't match your cluster isn't shift-left — it's just failing faster in the wrong environment."

The running example throughout the series is myapp: a Python 3.12 + FastAPI HTTP API on port 8080 that depends on PostgreSQL, run on a local k3d cluster.

Full article: https://dorokhovich.com/blog/local-k8s-inner-dev-loop?utm_source=devto&utm_medium=syndication&utm_campaign=local-k8s-inner-dev-loop