How to Obfuscate Python Scripts With PyArmor

Make your source code unreadable

Creating programs in Python is great: they’re fast to write and super easy to read. Sometimes, however, you don’t want your software code to be so easily understandable for many reasons ranging from trade secrets to enforcing paywalls.

The problem with distributing classic Python programs is that anyone can open the files in an editor and read the source code, possibly modifying parts that you, as a developer, don’t want users to touch, remove in-app paywalls, or get insights into how your program works.

As a developer, you can use code obfuscation to make the program files ideally unreadable to a human but still executable by a computer, thus preventing undesired eyes from sneaking into your application code. Obfuscation is similar to encryption in that the goal is the same: concealing a message, but encryption requires decryption to use the information, while obfuscated code can generally be run directly.

Installing PyArmor

To use PyArmor, you can install it through pip:

pip install pyarmor

If you wish to uninstall PyArmor, follow the instructions on their official documentation in the “Clean uninstallation” section.

Basic obfuscation with PyArmor

Let’s first create a simple Python script named script.py:

Obfuscating a Python script with PyArmor is as easy as running the following command in the console:

pyarmor obfuscate script.py

This will generate a dist folder containing the obfuscated Python file with the same name as the original along with runtime dependencies as shown in the folder structure below:

Let’s see what’s inside the output dist/script.py file:

That’s not very human-readable, is it? But you can still run it like this:

python3 dist/script.py

And it would work fine, as you can see from the console output:

Hello World

Obfuscating a whole package

PyArmor also allows you to obfuscate an entire Python package by using the --recursive option:

pyarmor obfuscate --recursive --output [output path] [module init path]
pyarmor obfuscate --recursive --output dist/module src/__init__.py

More secure obfuscation

If you wish to also obfuscate the strings contained in the source code, which might give some hints about what the program is doing, you can specify the --mix-str option like this:

pyarmor obfuscate --mix-str script.py

You may also specify an advanced obfuscation mode using the --advanced option:

pyarmor obfuscate --advanced 1 script.py

The advanced mode 1 is now deprecated, but it still works at the time of writing.

For even more protection, PyArmor offers a “Super Mode” and a “Super Plus Mode.” To use them, you have to specify it in the obfuscate command using the --advanced argument like this:

pyarmor obfuscate --advanced 2 script.py # Super Mode
pyarmor obfuscate --advanced 5 script.py # Super Plus Mode

Unfortunately, the Super Mode isn’t available for free trial users, though.

Add a license for more restrictions

PyArmor allows the developer to include a license in the obfuscated program by using the licenses command. A license can specify certain conditions that must be met to run the program, such as hard disk serial number, IP address, date, MAC address, and more.

To generate a license that specifies an expiry date, for example, you can use this command:

pyarmor licenses --expired [date] [license name]
pyarmor licenses --expired 2019-01-01 r001

And to include the license, you run the obfuscate command with the --with-license option:

pyarmor obfuscate --with-license [license path] script.py
pyarmor obfuscate --with-license licenses/r001/license.lic script.py

If you try to run a program whose license criteria aren’t met, it exits with the following message:

License is expired

For more information and license options, look at the official documentation.

Obfuscation performance

Code obfuscation is neat, but it comes with a slight runtime performance decrease. Obfuscation trades some execution speed for decreased readability by adding redundant and seemingly-random operations while still keeping the program behavior the same. Because of this, there are usually more instructions to run than clear code.

Although the few millisecond performance decreases are not relevant for small scripts, big programs might experience a significant speed difference when obfuscated. If you plan on obfuscating your Python applications, you should also consider this side of the coin.

For more information about the performance issues and how each mode affects the performance, you can read the official documentation, including a small benchmark.

Distributing the obfuscated program

You can package the obfuscated Python files into an executable for distribution using the pack command. To start, you must have pyinstaller installed first:

pip install pyinstaller

And then run the following command:

pyarmor pack script.py

In the dist folder, you will find the obfuscated bundled application to distribute.

Conclusion

To wrap it up, PyArmor allows you to obfuscate your Python source code to make it hard for unwanted eyes to look into your program files. While obfuscation is not perfect, and it’s possible to recover a somewhat-readable version of the code, it’s a further step toward a more secure application.

I hope you enjoyed this article. If you have anything to add, please share your thoughts in a comment. Thanks for reading!

If you’re interested in an alternative approach to development, check out this story below: