Shell¶

pyarmor is a command line tool, it must be run in the shell or terminal. If youknow nothing about shell command, usepyarmor-webui instead.

When commandpyarmor complains of argument error, unknown option etc. Pleaseuse option-h to list all the available options, and fix command syntaxerror by these hints. For example:

pyarmorobfuscate-h

Python¶

How to run Pythonhttps://docs.python.org/3.8/tutorial/interpreter.html#using-the-python-interpreter

Source Code Encoding¶

If the obfuscated scripts print unexpected output, you need learn this

https://docs.python.org/3.8/tutorial/interpreter.html#source-code-encoding

Then set the right source code encoding in the scripts, first run the plainscript to make sure everything is fine, then obfuscate the scripts again.

Python Import System¶

The obfuscated scripts need an extraRuntime Package to run, it’s acommon Python package, which could be imported as normal Python module orpackage. If it can’t be imported correctly, for example, not distributed withthe obfuscated scripts or stored in the wrong place, the obfuscated scripts mayraise exceptions like this:

ModuleNotFoundError:Nomodulenamed'app.pytransform'

This is not PyArmor’s error, just Python can not find it. In this case, you needknow Python how to import module, package, what’s absolute import and relativeimport, you must know what’ssys.path

https://docs.python.org/3.8/library/sys.html#sys.path

The obfuscated script is a very simple Python script, the first line is animport statement, the second line is a function call. For any import or nomodule found error, for example:

ImportError:Nomodulenamedmodel.NukepediaDB

Just think it as a common python script, check whether the module, package orextension file locates in the right place according to Python Import System. Ifnot, move the module, package or extension file to right path.

Refer to the following official document or by search engineer to understandPython Import System

https://docs.python.org/3.8/reference/simple_stmts.html#the-import-statement

PyInstaller¶

If you’d like to pack the obfuscated scripts to one executable, and your projectstructure is complex, you must knowPyInstaller and could pack your projectbyPyInstaller directly.

https://pyinstaller.readthedocs.io/en/stable/usage.html

Note

There are a lot of reporetedissues, search here first try to find sameissue.

Important

The issue may be marked asinvalid and be closed directly in any of:

• Not reported as template or missing necessary information
• There is the exact solution in the documentation

Could not find_pytransform¶

Generally, the dynamic library_pytransform is in theRuntime Package,before v5.7.0, it’s in the same path of obfuscated scripts. It may be:

• _pytransform.so in Linux
• _pytransform.dll in Windows
• _pytransform.dylib in MacOS

First check whether the file exists. If it exists:

• Check the permissions of dynamic library

  If there is no execute permissions in Windows, it will complain:[Error 5] Access is denied

• Check whetherctypes could load_pytransform:

  frompytransformimport_load_librarym=_load_library(path='/path/to/dist')

• Try to set the runtime path in theBootstrap Code of entryscript:

  frompytransformimportpyarmor_runtimepyarmor_runtime('/path/to/dist')

Still doesn’t work, report anissues

ERROR: Unsupport platform linux.xxx¶

Please refer toSupport Platforms

/lib64/libc.so.6: version ‘GLIBC_2.14’ not found¶

In some machines there is noGLIBC_2.14, it will raise this exception.

One solution is patching_pytransform.so by the following way.

First check version information:

readelf-V/path/to/_pytransform.so...Versionneedssection'.gnu.version_r'contains2entries:Addr:0x00000000000056e8Offset:0x0056e8Link:4(.dynstr)000000:Version:1File:libdl.so.2Cnt:10x0010:Name:GLIBC_2.2.5Flags:noneVersion:70x0020:Version:1File:libc.so.6Cnt:60x0030:Name:GLIBC_2.7Flags:noneVersion:80x0040:Name:GLIBC_2.14Flags:noneVersion:60x0050:Name:GLIBC_2.4Flags:noneVersion:50x0060:Name:GLIBC_2.3.4Flags:noneVersion:40x0070:Name:GLIBC_2.2.5Flags:noneVersion:30x0080:Name:GLIBC_2.3Flags:noneVersion:2

Then replace the entry ofGLIBC_2.14 withGLIBC_2.2.5:

• Copy 4 bytes at 0x56e8+0x10=0x56f8 to 0x56e8+0x40=0x5728
• Copy 4 bytes at 0x56e8+0x18=0x5700 to 0x56e8+0x48=0x5730

Here are sample commands:

xxd-s0x56f8-l4_pytransform.so|sed"s/56f8/5728/"|xxd-r-_pytransform.soxxd-s0x5700-l4_pytransform.so|sed"s/5700/5730/"|xxd-r-_pytransform.so

pyarmorobfuscate--platformcentos6.x86_64foo.py

‘pyarmor’ is not recognized issue¶

Ifpyarmor is installed by pip, please search “pyarmor” in the computer, thenrun full path pyarmor, or add path of pyarmor to environment variable PATH.

If not by pip, the equivalent of the pyarmor command is running Python script“pyarmor.py” found in the distribution folder.

__snprintf_chk: symbol not found¶

When run pyarmor in some dockers, it may raise this exception. Because thesedockers are built with musl-libc, but the default_pytransform.so is builtwith glibc,__snprintf_chk is missed in the musl-libc.

In this case, try to download the corresponding dynamic library:

# For x86_64pyarmordownloadmusl.x86_64.7# For arm64pyarmordownloadmusl.aarch64.3# For armv7lpyarmordownloadmusl.arm.0

And overwrite the old one which filename could be found in the traceback.

Before pyarmor v6.7.0, download the latest version by this way:

For x86/64http://pyarmor.dashingsoft.com/downloads/latest/alpine/_pytransform.so

For ARMhttp://pyarmor.dashingsoft.com/downloads/latest/alpine.arm/_pytransform.so

Apple M1 Hangs Issue¶

When pyarmor hangs in Apple M1, try these solutions:

• Remove the whole folder of~/.pyarmor/platforms, refer toClean uninstallation
• Upgrade pyarmor to latest version and use paid version.
• For trial version, export enviornment variablePYARMOR_PLATFORM=darwin.aarch64.0

Because the default core library of_pytransform.dylib uses some features likeJIT-compile which may be blocked by Apple M1.

Signing python interpreter with the corresponding entitlement may fix thisproblem, but I’m not sure. Refer tohttps://developer.apple.com/documentation/bundleresources/entitlements/com_apple_security_cs_allow-jit

Warning: code object xxxx isn’t wrapped¶

It means this function isn’t been obfuscated, because it includes somespecial instructions.

For example, there is 2-bytes instructionJMP 255, after the codeobject is obfuscated, the operand is increased to267, and theinstructions will be changed to:

EXTEND1JMP11

In this case, it’s complex to obfuscate the code object with wrapmode. So the code object is obfuscated with non wrap mode, but all theother code objects still are obfuscated with wrap mode.

In current version add some unused code in this function so that theoperand isn’t the critical value may avoid this warning.

Code object could not be obufscated with advanced mode 2¶

Because this function includes some jump instructions that couldn’t behandled. In this case, just refine this function, make sure the first statementwill not generate jump instruction. For example, assignment, function call orany simple statement. However, the compound statements, for examples,try,for,if,with,while etc. will generate the jump instructions. If thereis no anyway to refactor the function, insert the following statement at thebeginning of this function:

[None,None]

It will generate some instructions but doesn’t change anything.

Error: Try to run unauthorized function¶

If there is any filelicense.lic orpytransform.key in the currentpath, pyarmor maybe reports this error. One solution is to remove allof that files, the other solution to upgrade PyArmor to v5.4.5 later.

‘XXX’ codec can’t decode byte 0xXX¶

Add the exact source encode at the begin of the script. For example:

# -*- coding: utf-8 -*-

Refer tohttps://docs.python.org/2.7/tutorial/interpreter.html#source-code-encoding

If the source encode has been added into main script, it still raises thisissue. Please check the output log to find the exact script name, it may not themain script.

Why plugin doesn’t work¶

If the plugin script doesn’t work as expected, first check the plugin scriptcould be injected into the entry script by set Python debug flag:

# In linuxexportPYTHONDEBUG=y# In WindowssetPYTHONDEBUG=ypyarmorobfuscate--exact--plugincheck_ntp_timefoo.py

It will generate patched filefoo.py.pyarmor-patched, make sure the contentof plugin script has been inserted into the right place, and the verify functionwill be executed.

Thelicense.lic generated doesn’t work¶

The key is that the capsule used to obfuscate scripts must be same asthe capsule used to generate licenses.

TheGlobal Capsule will be changed if the trial license file ofPyArmor is replaced with normal one, or it’s deleted occasionally(which will be generated implicitly as running commandpyarmorobfuscate next time).

In any cases, generating new license file with the different capsulewill not work for the obfuscated scripts before. If the old capsule isgone, one solution is to obfuscate these scripts by the new capsuleagain.

NameError: name ‘__pyarmor__’ is not defined¶

NoBootstrap Code are executed before importing obfuscated scripts.

• When creating new process byPopen orProcess in modsubprocess ormultiprocessing, to be sure thatBootstrap Code will be called beforeimporting any obfuscated code in sub-process. Otherwise it will raise thisexception.
• Ifpytransform.py orpytransform/__init__.py raises this exception. Makesure it is not obfuscated, it must be plain script.
• Also check system moduleos,ctypes, make sure they’re not obfuscated, tryto use option--exclude to exclude the whole Python system library path.

How to checkBootstrap Code executed or not? One simple way is to insertone print statement before them. For example

print('Start to run bootstrap code')frompytransfromimportpyarmor_runtimepyarmor_runtime()

If the message is printed, then it’s OK. Removing the print statement and checkother causes.

The other solution for this issue isUsing Super Mode to obfuscate thescripts.

Marshal loads failed when running xxx.py¶

1. Check whether the version of Python to run obfuscated scripts is same as theversion of Python to obfuscate script
2. Run obfuscated script bypython -d to show more error message.
3. Be sure the capsule used to generated the license file is same as the capsuleused to obfuscate the scripts. The filename of the capsule will be shown inthe console when the command is running.
4. For cross platform obfuscation, make sure the dynamic library feature is setcorrectly, refer toObfuscating scripts with different features

_pytransform can not be loaded twice¶

When the functionpyarmor_runtime is called twice, it will complaint_pytransform can not be loaded twice

For example, if an obfuscated module includes the following lines:

frompytransformimportpyarmor_runtimepyarmor_runtime()__pyarmor__(....)

When importing this module from entry script, it will report thiserror. The first 2 lines should be in the entry script only, not inthe other module.

This limitation is introduced from v5.1, to disable this check, justeditpytransform.py and comment these lines in functionpyarmor_runtime:

if_pytransformisnotNone:raisePytransformError('_pytransform can not be loaded twice')

Check restrict mode failed¶

Use obfuscated scripts in wrong way, by default all the obfuscatedscripts can’t be changed any more.

Besides packing the obfuscated scripts will report this erroreither. Do not pack the obfuscated scripts, but pack the plain scriptsdirectly.

For more information, refer toRestrict Mode

Protection Fault: unexpected xxx¶

Use obfuscated scripts in wrong way, by default, all the runtime filescan’t be changed any more. Do not touch the following files

• pytransform.py
• _pytransform.so/.dll/.dylib

If the entry script is obfuscated by new version, but the runtime files arestill old, it may raise this exception. Using option--no-cross-protectionto disable this protection, or using option--runtime to specify the sameruntime files when obfuscating the scrpits, could fix this issue.

For more information, refer toSpecial Handling of Entry Script

Run obfuscated scripts reports: Invalid input packet¶

Mixing trial version and purchased version to obfuscate scripts and generatelicense.lic also may raise this exception. Make sure all the files generatedby trial version, for example, obfusbcated script, license file and runtimefiles, are removed.

Make sure the runtime module or packagepytransform imported by the obfuscatedscripts is the one distributed with the obfuscated scripts. For example, runningthe obfuscated scriptspython dist/foo.py in the source path of pyarmorpackage may rasie this exception, becausepytransform.py of pyarmor will beimported by thedist/foo.py unexpectedly.

If the scripts are obfuscated in different platform, check the notes inDistributing Obfuscated Scripts To Other Platform

Before v5.7.0, check if there is any oflicense.lic orpytransform.key inthe current path. Make sure they’re generated for the obfuscated scripts. Ifnot, rename them or move them to other path.

Because the obfuscated scripts will first search the current path, then searchthe path of runtime modulepytransform.py to find the filelicense.lic andpytransform.key. If they’re not generated for the obfuscated script, thiserror will be reported.

OpenCV fails because ofNEON - NOT AVAILABLE¶

In some Raspberry Pi platform, run the obfuscated scripts to importOpenCV fails:

*******************************************************************FATALERROR:**ThisOpenCVbuilddoesn't support current CPU / HW configuration ****UseOPENCV_DUMP_CONFIG=1environmentvariablefordetails*******************************************************************Requiredbaselinefeatures:NEON-NOTAVAILABLEterminatecalledafterthrowinganinstanceof'cv :: Exception'what():OpenCV(3.4.6)/home/pi/opencv-python/opencv/modules/core/src/system.cpp:538:error:(-215:Assertionfailed)MissingsupportforrequiredCPUbaselinefeatures.CheckOpenCVbuildconfigurationandrequiredCPU/HWsetup.infunction'initialize'

One solution is to specify optioin--platform tolinux.armv7.0:

pyarmorobfuscate--platformlinux.armv7.0foo.pypyarmorbuild--platformlinux.armv7.0pyarmorruntime--platformlinux.armv7.0

The other solution is to set environment variablePYARMOR_PLATFORMtolinux.armv7.0. For examples:

PYARMOR_PLATFORM=linux.armv7.0pyarmorobfuscatefoo.pyPYARMOR_PLATFORM=linux.armv7.0pyarmorbuildOr,exportPYARMOR_PLATFORM=linux.armv7.0pyarmorobfuscatefoo.pypyarmorbuild

How to customize error message¶

Refer toHow to customize error message

undefined symbol: PyUnicodeUCS4_AsUTF8String¶

If Python interpreter is built with UCS2, it may raises this issue when runningsuper mode obufscated scripts. In this case, try to obfuscate script withplatformcentos6.x86_64, it’s built with UCS2. For example:

pyarmorobfuscate--advanced2--platformcentos6.x86_64foo.py

NameError: name ‘__armor_wrap__’ is not defined¶

IfRestrict Mode is set to 4 or 5, it may report this issue. In this casetry to set restrict mode to 2.

If it’s raised in the object method__del__, upgrade pyarmor to v6.7.3+, andobfuscate the scripts again.

Also refer toUsing restrict mode with threading and multiprocessing andnext question.

Object method__del__ raise NameError exception¶

If method__del__ raises this exception:

NameError:name'__armor_enter__'isnotdefinedNameError:name'__armor_wrap__'isnotdefined

Please upgrade pyarmor to v6.7.3+, and obfuscate the scripts again, and makesure new runtime package is generated.

If the scripts is obfuscated by non super mode and python is 3.7 and later,please obfuscate the scrits by super mode. Or refine the scripts, do notobfuscate the object method__del__. For example

classMyData:...deflambda_del(self):# Real code for method __del__...__del__=lambda_del

Any function name which starts withlambda_ will not be obfuscated by pyarmor,in above example, the methodlambda_del is not obfuscated, so__del__ is.

The other solution is not obfuscating the script which includes__del__ bycopying the plain script to overwrite the obfsucated one. Or obfuscate thisscript by--obf-code0.

SystemError: module filename missing¶

When obfsucating the scripts by super mode, and with outer license, it maycomplain of this error if the obfuscated scripts could not find the license filelicense.lic in the current path.

Iflicense.lic is in the other path, set environment variablePYARMOR_LICNSEto it with full path, for example:

exportPYARMOR_LICNSE=/path/to/license.lic

Android protection problem¶

Most of Android system don’t allow load dynamic library in the data path, butthere is one_pytransform.so in the runtime package of the obfuscated scripts,so it may raise exception like this:

dlopenfailed:couldn't map "/storage/emulated/0/dist/_pytransform.so"segment1:Operationnotpermitted

Please consult Android development document, copy the whole folderpytransformto right location where Android allow to load dynamic library, and setPYTHONPATH or any other way only if Python could find and import it.

libpython3.9.so.1.0: cannot open shared object file¶

If missing any python core library such aspython39.dll,libpython3.9.so,etc, make sure this python interpreter is built with–enable-shared. Bydefault, the runtime extensionpytransform is linked to python dynamiclibrary.

In Linux platform, try to installlibpython3.9 byapt or any otherpacakge manage tool.

error: unrecognized arguments¶

For option-e and-x, it need an extra whitespace in option value, otherwiseit will complain oferror: unrecognized arguments. For exmaple:

# Wrong, no heading whitespace before --advanced 2pyarmorpack-x"--advanced 2"...# Rightpyarmorpack-x" --advanced 2"...

If no-e or-x is used, please check the man page ofpack tounderstand all support options.

The final bundle does not work¶

First of all, please read the man page ofpack completely.

Next make sure the scripts could pack by PyInstaller directly and the finalbundle works. For example:

pyinstallerfoo.pydist/foo/foo

If the final bundle complains of no module found, it need some extra PyInstalleroptions, please refer tohttps://pyinstaller.readthedocs.io

Then make sure the obfuscated scripts could work without packing. For example:

pyarmorobfuscatefoo.pypythondist/foo.py

If both of them OK, remove the output pathdist and PyInstaller cached pathbuild, then pack the script with--debug:

pyarmorpack--debugfoo.py

The build files will be kept, the patchedfoo-patched.spec could be used bypyinstaller to pack the obfuscated scripts directly, for example:

pyinstaller-y--cleanfoo-patched.spec

Check this patched.spec and change options in this.spec file, make surethe final bundle could work.

Also refer toRepack PyInstaller bundle with obfuscated scripts, makesure it works by this way.

No module name pytransform¶

If report this error as running commandpyarmor pack:

• Make sure the script specified in the command line is not obfuscated

• Runpack with extra option--clean to remove cachedmyscript.spec:

  pyarmorpack--cleanfoo.py

NameError: name ‘__pyarmor__’ is not defined¶

Check the traceback to find which script raises this exception, it’s helpful tofind the problem:

• Ifpytransform.py orpytransform/__init__.py raises this exception. Makesure it is not obfuscated, it must be plain script.

• Also check system moduleos,ctypes, make sure they’re not obfuscated. Inthis case, try to exclude the Python system library path, for example:

  pyarmorpack-x" --exclude venv"foo.py

  More information refer topack

• Try to only copy your own scripts to an empty path, then pack it in this path.

• If it works in trial version, but fails after pyarmor is registered, try tomake aClean uninstallation

Purchased pyarmor is not private¶

Even obfuscated with purchased version, license from trial version works:

• Make sure commandpyarmor register shows correct registration information
• Make aClean uninstallation, and register again
• Make sure the current user is same as the one to register pyarmor
• Make sure environment variablePYARMOR_HOME is not set
• Try to reboot system.

Could not query registration information¶

I tried to register in pyarmor with using the command and log:

~%pyarmorregisterpyarmor-regfile-1.zipINFOPyArmorVersion6.5.2INFOStarttoregisterkeyfile:pyarmor-regfile-1.zipINFOSaveregistrationdatato:/Users/Jondy/.pyarmorINFOExtractinglicense.licINFOExtracting.pyarmor_capsule.zipINFOThiskeyfilehasbeenregisteredsuccessfully.

Watching whether I am registered, I got this output:

~%pyarmorregisterINFOPyArmorVersion6.5.2PyArmorVersion6.5.2RegistrationCode:pyarmor-vax-000383Becauseofinternetexception,couldnotqueryregistrationinformation.

Ping domainapi.dashingsoft.com, make sure ip address is resolved like this:

~%pingapi.dashingsoft.comPINGapi.dashingsoft.com(119.23.58.77):56databytesRequesttimeoutforicmp_seq0Requesttimeoutforicmp_seq1

If not, add one line in the/etc/hosts:

119.23.58.77pyarmor.dashingsoft.com

Obfuscate scripts in cross platform¶

From v5.6.0 to v5.7.0, there is a bug for cross platform. The scripts obfuscatedin linux64/windows64/darwin64 don’t work after copied to one of this targetplatform:

armv5,android.aarch64,ppc64le,ios.arm64,freebsd,alpine,alpine.arm,poky-i586

Is there anyway we could get an evaluation license¶

Q: Is there anyway we could get an evaluation license that lifts therestriction of large file sizes to test it on our systems? Perhaps restricted to1-2 days with the promise that we will purchase if it fits our needs.

A: There is no evaluation license for pyarmor at this time.

For all of features changed by pyarmor, please check this sectionhttps://pyarmor.readthedocs.io/en/latest/understand-obfuscated-scripts.html#the-differences-of-obfuscated-scripts

Generally if your scripts don’t use any mentioned features, and any lowerfeatures of Python like visiting frame (sys._getframe), inspecting code objectdirectly, it should work with pyarmor.

One license of pyarmor cost only a small amount of money, even purchasing onefor evalution is not too hard to make a decision.

How easy is to recover obfuscated code¶

If someone tries to break the obfuscation, he first must be an expert in thefield of reverse engineer, and be an expert of Python, who should understand thestructure of code object of python, how python interpreter each instruction. Ifsomeone of them start to reverse, he/she must step by step thousands of machineinstruction, and research the algorithm by machine codes. So it’s not an easything to reverse pyarmor.

How to get receipt or invoice¶

MyCommerce handles all the sales of pyarmor

Please get help from this page for order/recipt/invoice issue

https://www.mycommerce.com/shopper-support/

Or contact “ClientSupport@MyCommerce.com” directly

Would pyarmor be able to provide an evaluation license¶

Sorry, pyarmor license could be work even offline, so there is no evaluationlicense.

Generally the obfuscated scripts could replace the original scriptsseamlessly. Excpet it uses the features changed by pyarmor, here list allThe Differences of Obfuscated Scripts

Most of packages could work with pyarmor, for a few packages, pyarmor also worksafter patching these packages simplify. Only those packages which visit bytecode or something like this could not work with pyarmor at all.