# python-minifier shrinks Python source until it fits a template

> python-minifier rewrites Python source into its most compact representation, renaming locals to single letters and folding statements onto shared lines. It was built so that an AWS Lambda function under 4KiB can still be embedded in a CloudFormation template, and its output only runs on the interpreter version that produced it.

**dflook/python-minifier** — Transform Python source code into its most compact representation

- Repository: https://github.com/dflook/python-minifier
- Stars: 721 · Forks: 54
- Language: Python
- License: MIT
- Published: 2026-10-21 · Updated: 2026-10-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/dflook-python-minifier

## Built for a 4KiB limit on embedded Lambda source

python-minifier exists because of a specific AWS constraint. CloudFormation templates may contain AWS Lambda function source code embedded in them, but only if the function is less than 4KiB. The author wrote the package so that he could write Python normally and still embed the module in a template.

That origin explains the design decisions better than a general purpose minifier would. The tool is not trying to be a good JavaScript-style minifier with pretty output and source maps. It is trying to answer one question: how few bytes can this module be while still being valid Python.

The transformation is aggressive and visible. Given a handler function with ordinary names, the output renames locals to single letters, hoists repeated string literals into variables at the top of the function, joins statements with semicolons, removes optional parentheses, and indents with tabs:

```python
def handler(event,context):
	L='OldResourceProperties';K='Tags';J='None';H='SUCCESS';G='RequestType';E='Status';D=context;B='PhysicalResourceId';A=event;l.info(A)
```

Notice what happened to the string literals. Values used more than once, such as `PhysicalResourceId` and `SUCCESS`, are bound to a single letter once and then reused, so the repeated text is paid for only once. The `except Exception as ex` handler even rebinds the exception to `I`, freeing a name. The result is a module that is considerably shorter and considerably harder to read, which is the intended trade.

The project is published on PyPI as `python-minifier`, the documentation lives at `dflook.github.io/python-minifier`, and there is a hosted page at `python-minifier.com` where you can try it out. The author is Daniel Flook and the licence is MIT.

## The output is bound to the interpreter that produced it

The most important operational fact about the tool is stated plainly in the project documentation: python-minifier depends on the Python interpreter for parsing source code, and it outputs source code compatible with the version of the interpreter it is run with. If you minify code written for Python 3.11 using python-minifier running with Python 3.12, the minified code may only run with Python 3.12.

This is not a bug, it is a consequence of how the tool works. The parsing is done by the interpreter's own parser, and the transformations are applied against the syntax that interpreter understands. The output is a syntactically valid program for that version, not for every version.

For the use case the author had, this is acceptable, because the minified module is going to be deployed to a Lambda runtime that the author also controls. For a general distribution channel it is a serious constraint. If you minify a library and ship it to users, the users' interpreter version becomes part of your support matrix, and the tool will not warn you about a mismatch because it cannot know where the output will run.

The version range is wide on both sides of the modern range. The tool currently supports Python 2.7 and Python 3.3 to 3.15, previous releases supported Python 2.6, and the package metadata declares `python_requires` as 2.7 and above with 3.0, 3.1 and 3.2 excluded and 3.16 as the upper bound.

## Installing and running pyminify on a file

Installation is a single pip install:

```bash
$ pip install python-minifier
```

Minifying a file writes the result to standard output, so you redirect it yourself:

```bash
$ pyminify hello.py
```

The same thing is available as a library, and the documented example is short enough to read in full:

```python
import python_minifier

with open('hello.py') as f:
    print(python_minifier.minify(f.read()))
```

So the integration path for a build script is straightforward: read the file, hand the text to `minify`, write the returned string wherever it needs to go. The command line tool and the API are the same transformation, and the command is really just a thin wrapper over the function.

The package is a source distribution with a `src/` layout, and the version is derived from the git tags through `use_scm_version` in `setup.py` with `setuptools_scm`, so the published version tracks the commit rather than being written by hand. It is classified as Production/Stable, and the release history shows regular work: 3.2.0 on 2025-12-31, 3.3.0 on 2026-09-04 and 3.4.0 on 2026-09-29, with the last push on 2026-10-09.

## Type hints ship with the package, and the test suite is unusual

python-minifier is typed. The package data includes `py.typed` along with `*.pyi` stubs for the package itself and for its `rename/` and `transforms/` subpackages, which tells you something about the internal structure: renaming and transformation are separate concerns implemented as their own modules rather than one monolithic pass.

The repository layout shows the same emphasis on correctness rather than only on output size. Alongside the ordinary `test/` directory there is `corpus_test/`, `hypo_test/`, `typing_test/` and `xtest/`, and there are two tox configurations, `tox.ini` and `tox-windows.ini`, so the suite is run on both Unix and Windows. There is a `docker/` directory, a `docs/` directory for the published documentation, and a `CHANGELOG.md` linked from the package metadata.

A hypothesis-style test directory is worth calling out, because a minifier is exactly the kind of program where a bug turns into a syntax error in someone else's code. The useful mental model for a reviewer is that the tool's output must be re-parsed and must behave the same as the input, and a test layout built around generated inputs, type checks and a corpus is trying to hold that line.

The result is that the tool ships with type information and a fairly serious test apparatus, which is unusual for a utility that most people will run once and forget.

## Where python-minifier is the wrong tool

The first case is code anybody has to read. The transformation removes names, folds statements onto shared lines and rewrites literals into single letter variables. If the minified module is going to sit in a repository where a human might need to debug it, or where a traceback will point at it, the compact form is a liability rather than a saving.

The second is the assumption that minification is how you reduce a deployment package. The author of the project framed the problem correctly for his own case, where a hard limit on the size of embedded source forces the question, but the general answer to shipping less code is usually not to obfuscate the source. Packaging, compression at rest and bundling are different mechanisms with different trade-offs, and none of them require the code to be unreadable.

The third is distribution across interpreter versions, which the tool itself warns about. If the minified output will run on machines you do not control, the interpreter that produced it becomes part of the contract, and the project says the minified code may only run with the newer version.

The fourth is that the tool only handles Python. There is no JavaScript or TypeScript mode, no source maps, and no debugging story. If what you need to shrink is a front end bundle rather than a Python module embedded in a template, this is the wrong package, and the project is honest about being a Python tool rather than a general minifier.

## Conclusion

python-minifier fits a team that has to fit Python source into a fixed size payload, most obviously an AWS Lambda function embedded in a CloudFormation template, and it fits people who simply want to ship smaller source. It does not fit a reader who needs readable code, and it does not fit a project that ships Python to machines running a different interpreter version, because the minified output is tied to the interpreter that produced it. Check three things first: that the interpreter you minify with is the interpreter your users run, since code written for 3.11 minified under 3.12 may only run on 3.12, that the 4KiB constraint is genuinely about source size rather than the deployment package, and which version you pin, since 3.4.0 was released on 2026-09-29 while the last push was on 2026-10-09.

## FAQ

### How do I install and run python-minifier?

Install it with `pip install python-minifier`, then run `pyminify hello.py` to minify a file to standard output. The same result comes from the API with `python_minifier.minify` on the source text.

### Which Python versions does python-minifier support?

It runs with and can minify code written for Python 2.7 and Python 3.3 to 3.15, previous releases supported Python 2.6, and the package metadata excludes 3.0, 3.1 and 3.2 and caps the range below 3.16.

### Why does the minified output only run on the interpreter version that produced it?

The tool depends on the interpreter to parse the source and emits code compatible with the version it runs under. The documentation notes that code written for Python 3.11 and minified with Python 3.12 may only run with Python 3.12.

### What does python-minifier actually change in the source?

It rewrites the source into a compact form: local names become single letters, repeated string literals are hoisted into variables, statements are joined with semicolons and indentation uses tabs. The project shows a CloudFormation handler function transformed this way.

### What licence is python-minifier released under?

The MIT licence, with the full text in the LICENSE file at the repository root, and the package metadata declares the same licence with Daniel Flook as author.

## Sources

- [dflook/python-minifier on GitHub](https://github.com/dflook/python-minifier)
- [Issues](https://github.com/dflook/python-minifier/issues)
- [License: MIT](https://github.com/dflook/python-minifier/blob/main/LICENSE)
- [README](https://github.com/dflook/python-minifier/blob/main/README.md)
- [Releases](https://github.com/dflook/python-minifier/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/dflook-python-minifier