1.1. Getting Started¶
- What’s Pyarmor
- Installation from PyPI
- Obfuscating one script
- Obfuscating one package
- Expiring obfuscated scripts
- Binding obfuscated scripts to device
- Packaging obfuscated scripts
- Something need to know
- What to read next
- How the documentation is organized
New to Pyarmor? Well, you came to the right place: read this material to quickly get up and running.
Pyarmor is a command-line tool designed for obfuscating Python scripts, binding obfuscated scripts to specific machines, and setting expiration dates for obfuscated scripts.
- Seamless Replacement: Obfuscated scripts remain as standard .py files, allowing them to seamlessly replace the original Python scripts in most cases.
- Balanced Obfuscation: Offers multiple ways to obfuscate scripts to balance security and performance.
- Irreversible Obfuscation: Renames functions, methods, classes, variables, and arguments.
- C Function Conversion: Converts some Python functions to C functions and compiles them into machine instructions using high optimization options for irreversible obfuscation.
- Script Binding: Binds obfuscated scripts to specific machines or sets expiration dates for obfuscated scripts.
- Themida Protection: Protects obfuscated scripts using Themida (Windows only).
On Linux or MacOS, you should open your terminal and run the following command:
$ pip install -U pyarmor
On Windows, you should open Command Prompt (Win-r and type cmd) and run the same command:
C:\> pip install -U pyarmor
After installation, type pyarmor --version on the command prompt. If everything worked fine, you will see the version number for the Pyarmor package you just installed.
Not all the platforms are supported, more information check Building Environments
Here it’s the simplest command to obfuscate one script
$ pyarmor gen foo.py
gen could be replaced with
$ pyarmor g foo.py $ pyarmor generate foo.py
This command generates an obfuscated script
dist/foo.py, which is a valid Python script, run it by Python interpreter:
$ python dist/foo.py
Check all generated files in the default output path:
$ ls dist/ ... foo.py ... pyarmor_runtime_000000
There is an extra Python package
pyarmor_runtime_000000, which is required to run the obfuscated script.
dist/foo.py to another machine doesn’t work, instead copy all the files in the
Why? It’s clear after checking the content of
from pyarmor_runtime_000000 import __pyarmor__ __pyarmor__(__name__, __file__, ...)
Actually the obfuscated script can be taken as normal Python script with dependent package
pyarmor_runtime_000000, use it as it’s not obfuscated.
Please run this obfuscated in the machine with same Python version and same platform, otherwise it doesn’t work. Because
pyarmor_runtime_000000 has an extension module, it’s platform-dependent and bind to Python version.
DO NOT install Pyarmor in the Target Device, Python interpreter could run the obfuscated scripts without Pyarmor.
Now let’s do a package.
-O is used to set output path
dist2 different from the default:
$ pyarmor gen -O dist2 src/mypkg
Check the output:
$ ls dist2/ ... mypkg ... pyarmor_runtime_000000 $ ls dist2/mypkg/ ... __init__.py
All the obfuscated scripts in the
dist2/mypkg, test it:
$ cd dist2/ $ python -C 'import mypkg'
If there are sub-packages, using
-r to enable recursive mode:
$ pyarmor gen -O dist2 -r src/mypkg
Also it works to copy the whole path
dist2 to another machine. But it’s not convenience, the better way is using
-i to generate all the required files inside package path:
$ pyarmor gen -O dist3 -r -i src/mypkg
Check the output:
$ ls dist3/ ... mypkg $ ls dist3/mypkg/ ... __init__.py ... pyarmor_runtime_000000
Now everything is in the package path
dist3/mypkg, just copy the whole path to any target machine.
dist3/mypkg/__init__.py with above section
dist2/mypkg/__init__.py to understand more about obfuscated scripts
It’s easy to set expire date for obfuscated scripts by
-e. For example, generate obfuscated script with the expire date to 30 days:
$ pyarmor gen -O dist4 -e 30 foo.py
Run the obfuscated scripts
dist4/foo.py to verify it:
$ python dist4/foo.py
It checks network time, make sure your machine is connected to internet.
Let’s use another form to set past date
$ pyarmor gen -O dist4 -e 2020-12-31 foo.py
dist4/foo.py should not work:
$ python dist4/foo.py
If expire date has a leading
., it will check local time other than NTP server. For examples:
$ pyarmor gen -O dist4 -e .30 foo.py $ pyarmor gen -O dist4 -e .2020-12-31 foo.py
For this form internet connection is not required in target machine.
Distributing the expired script is same as above, copy the whole directory
dist4/ to target machine.
Suppose got target machine hardware information:
IPv4: 22.214.171.124 Ethernet Addr: 00:16:3e:35:19:3d Hard Disk Serial Number: HXS2000CN2A
-b to bind hardware information to obfuscated scripts. For example, bind
dist5/foo.py to Ethernet address:
$ pyarmor gen -O dist5 -b 00:16:3e:35:19:3d foo.py
dist5/foo.py only could run in target machine.
It’s same to bind IPv4 and serial number of hard disk:
$ pyarmor gen -O dist5 -b 126.96.36.199 foo.py $ pyarmor gen -O dist5 -b HXS2000CN2A foo.py
It’s possible to combine some of them. For example:
$ pyarmor gen -O dist5 -b "00:16:3e:35:19:3d HXS2000CN2A" foo.py
Only both Ethernet address and hard disk are matched machine could run this obfuscated script.
Distributing scripts bind to device is same as above, copy the whole directory
dist5/ to target machine.
Remember again, the obfuscated script is normal Python script, use it as it’s not obfuscated.
mypkg structure like this:
projects/ └── src/ └── mypkg/ ├── __init__.py ├── utils.py └── config.json
First make output path
projects/dist6 for obfuscated package:
$ cd projects $ mkdir dist6
Then copy package data files to output path:
$ cp -a src/mypkg dist6/
Next obfuscate scripts to overwrite all the
.py files in
$ pyarmor gen -O dist6 -i src/mypkg
The final output:
projects/ ├── README.md └── src/ └── mypkg/ ├── __init__.py ├── utils.py └── config.json └── dist6/ └── mypkg/ ├── __init__.py ├── utils.py ├── config.json └── pyarmor_runtime_000000/__init__.py
src/mypkg, the only difference is
dist6/mypkg has an extra sub-package
pyarmor_runtime_000000. The last thing is packaging
dist6/mypkg as your prefer way.
New to Python packaging? Refer to Python Packaging User Guide
There is binary extension module
pyarmor_runtime in extra sub-package
pyarmor_runtime_000000, here it’s package content:
$ ls dist6/mypkg/pyarmor_runtime_000000 ... __init__.py ... pyarmor_runtime.so
Generally using binary extensions means the obfuscated scripts require
pyarmor_runtime be created for different platforms, so they
- only works for platforms which provides pre-built binaries, refer to Building Environments
- may not be compatible with different builds of CPython interpreter. For example, when obfuscating scripts by Python 3.8, they can’t be run by Python 3.7, 3.9 etc.
- often will not work correctly with alternative interpreters such as PyPy, IronPython or Jython
Another disadvantage of relying on binary extensions is that alternative import mechanisms (such as the ability to import modules directly from zipfiles) often won’t work for extension modules (as the dynamic loading mechanisms on most platforms can only load libraries from disk).
There is a complete installation guide that covers all the possibilities:
- install pyarmor by source
- call pyarmor from Python script
- clean uninstallation
Next is Basic Tutorial. It covers
- using more option to obfuscate script and package
- using outer file to store runtime key
- localizing runtime error messages
- packing obfuscated scripts and protect system packages
And then Advanced Tutorial, some of them are not available in trial pyarmor
- 2 irreversible obfuscation: RFT mode, BCC mode pro
- Customization error handler
- runtime error internationalization
- cross platform, multiple platforms and multiple Python version
Also you may be interesting in this guide Highest security and performance
Pyarmor has a lot of documentation. A high-level overview of how it’s organized will help you know where to look for certain things:
- Part 1: Tutorials now you’re reading.
- Part 2: How To guides are recipes. They guide you through the steps involved in addressing key problems and use-cases. They are more advanced than tutorials and assume some knowledge of how Python works.
- Part 3: References guides contain key concepts, man page, configurations and other aspects of Pyarmor machinery.
- Part 4: Topics guides insight into key topics and provide useful background information and explanation. They describe how it works and how to use it but assume that you have a basic understanding of key concepts.
- Part 5: Licenses describes EULA of Pyarmor, the different Pyarmor licenses and how to purchase Pyarmor license.