Skip to content

Fix compatibility and add language support #35

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
liuyuchen012 wants to merge 2 commits into
base: master
Choose a base branch
from
Open

Fix compatibility and add language support #35

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
30cd21a
Fix compatibility and add language support
liuyuchen012 Dec 21, 2025
06234a4
Revise README for clarity and bilingual support
liuyuchen012 Dec 21, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
248 changes: 194 additions & 54 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,54 +1,194 @@
Author: In Ming Loh (inming.loh@countercept.com - @tantaryu) <br />
Company: Countercept (@countercept) <br />
Website: https://www.countercept.com <br />

## Introduction
A script that helps researcher to unpack and decompile executable written in python. However, right now this only supports executable created with py2exe and pyinstaller.

This script glues together several tools available to the community. Hopefully, this can help people in their daily job. Several YARA rules are available to determine if the executable is written in python (This script also confirms if the executable is created with either py2exe or pyinstaller).

## Requirements
- Python 2.7 or later.
- Install all the dependency needed:<br/>
`pip2 install --user -r requirements.txt`<br/>
or if you fancy to have your dependency installed with root permission<br/>
`sudo pip2 install -r requirements.txt`


## Getting Started
- python python_exe_unpack.py -i [malware.exe]
* pyinstaller
* A folder will be created with the original filename concatenated with "_extracted". For example: "malware.exe_extracted".
* The main python file that contains the logic will usually be the file without any extension (In the folder that concatenated with "_extracted"). In the following example, "hello" is the one that contains the main python logic:<br/>
`-rw-rw-r-- 1 testuser testuser 70K Nov 14 13:08 bz2.pyd`<br/>
`-rw-rw-r-- 1 testuser testuser 993K Nov 14 13:08 _hashlib.pyd`<br/>
`-rw-rw-r-- 1 testuser testuser 111 Nov 14 13:08 hello`<br/>
`-rw-rw-r-- 1 testuser testuser 1009 Nov 14 13:08 hello.exe.manifest`<br/>
`-rw-rw-r-- 1 testuser testuser 1.1K Nov 14 13:08 Microsoft.VC90.CRT.manifest`<br/>
`-rw-rw-r-- 1 testuser testuser 220K Nov 14 13:08 msvcm90.dll`<br/>
`-rw-rw-r-- 1 testuser testuser 557K Nov 14 13:08 msvcp90.dll`<br/>
`-rw-rw-r-- 1 testuser testuser 638K Nov 14 13:08 msvcr90.dll`<br/>
`-rw-rw-r-- 1 testuser testuser 628K Nov 14 13:08 out00-PYZ.pyz`<br/>
`drwxrwxr-x 2 testuser testuser 12K Nov 14 13:08 out00-PYZ.pyz_extracted`<br/>
`-rw-rw-r-- 1 testuser testuser 5.2K Nov 14 13:08 pyiboot01_bootstrap`<br/>
`-rw-rw-r-- 1 testuser testuser 2.5K Nov 14 13:08 pyimod01_os_path`<br/>
`-rw-rw-r-- 1 testuser testuser 12K Nov 14 13:08 pyimod02_archive`<br/>
`-rw-rw-r-- 1 testuser testuser 22K Nov 14 13:08 pyimod03_importers`<br/>
`-rw-rw-r-- 1 testuser testuser 0 Nov 14 13:08 pyi-windows-manifest-filename hello.exe.manifest`<br/>
`-rw-rw-r-- 1 testuser testuser 2.6M Nov 14 13:08 python27.dll`<br/>
`-rw-rw-r-- 1 testuser testuser 10K Nov 14 13:08 select.pyd`<br/>
`-rw-rw-r-- 1 testuser testuser 234 Nov 14 13:08 struct`<br/>
`-rw-rw-r-- 1 testuser testuser 671K Nov 14 13:08 unicodedata.pyd`<br/>
* pyinstaller has an option that can encrypt python bytecode. This script will try to decrypt it and decompile the decrypted code.
* py2exe
* The result of unpacking and decompiling will be located in folder "unpacked" or the location you specify.
* If error like this shows "Error in unpacking the exe. Probably due to version incompability (exe created using python 2 and run this script with python 3)", try setting your python to a different version than the one you are using. Eg: "alias python=python2" or "alias python=python3"

- python python_exe_unpack.py -p [pyc file]
* In the above example, sometimes the python file that contains the main logic will not be in the format that uncompyle6 accept (Missing python magic numbers). The above command will prepend magic numbers and decompile it (If magic number is already preprended it will not add it and just proceed with decompiling).

## Credits
- Extreme Coders for their pyinstxtractor.py script to help unpack pyinstaller executable.
- Extreme Coders for their instruction on how to decrypt encrypted python byte code: https://0xec.blogspot.sg/2017/02/extracting-encrypted-pyinstaller.html
- unpy2exe
- uncompyle6
# PyInstaller Extractor v1.8.1

## 项目描述 / Project Description

PyInstaller Extractor 是一个用于解包 PyInstaller 生成的独立可执行文件的工具。该工具无需安装 PyInstaller，脚本本身包含了所有必要功能。

PyInstaller Extractor is a tool for unpacking standalone executables generated by PyInstaller. This tool does not require PyInstaller installation as the script contains all necessary functionality.

## 功能特点 / Features

- 支持 PyInstaller 3.2, 3.1, 3.0, 2.1, 2.0 版本
- 无需安装 PyInstaller
- 支持 Python 2.x 和 3.x
- 中英双语输出
- 自动处理加密的 PYZ 归档
- 支持 PYZ 归档中的子目录

- Supports PyInstaller versions 3.2, 3.1, 3.0, 2.1, 2.0
- No PyInstaller installation required
- Compatible with both Python 2.x and 3.x
- Bilingual output (English and Chinese)
- Automatic handling of encrypted PYZ archives
- Supports subdirectories in PYZ archives

## 系统要求 / Requirements

- Python 2.6 或更高版本 / Python 2.6 or higher
- 建议使用与创建可执行文件时相同的 Python 版本运行此脚本 / It is recommended to run this script with the same Python version used to create the executable

## 安装与使用 / Installation and Usage

### 基本用法 / Basic Usage

1. 将 `pyinstxtractor2026.py` 脚本复制到可执行文件所在的目录
2. 运行脚本并指定可执行文件名作为参数

Copy the `pyinstxtractor2026.py` script to the directory containing your executable
Run the script with the executable filename as a parameter

```bash
# Windows
python pyinstxtractor2026.py <filename.exe>

# Linux/Mac
python3 pyinstxtractor2026.py <filename>
```

### 命令行参数 / Command Line Arguments

```bash
# 提取指定文件 / Extract specified file
python pyinstxtractor2026.py your_program.exe

# 查看帮助 / View help
python pyinstxtractor2026.py
```

## 输出说明 / Output Description

脚本运行后，会在当前目录下创建一个名为 `[可执行文件名]_extracted` 的文件夹，其中包含所有解包的文件：

After running the script, a folder named `[executable_filename]_extracted` will be created in the current directory, containing all unpacked files:

1. **原始文件** - 解包出的原始资源文件
2. **PYZ 归档** - 包含 Python 字节码文件的归档
3. **PYZ 提取内容** - 以 `_extracted` 为后缀的文件夹，包含解包的 `.pyc` 文件

1. **Original files** - Unpacked original resource files
2. **PYZ archives** - Archives containing Python bytecode files
3. **PYZ extracted contents** - Folders with `_extracted` suffix containing unpacked `.pyc` files

## 使用示例 / Usage Examples

### 示例 1: 解包标准可执行文件 / Example 1: Unpacking a standard executable

```bash
# 解包 myapp.exe / Unpack myapp.exe
python pyinstxtractor2026.py myapp.exe

# 输出目录 / Output directory
# myapp.exe_extracted/
# ├── myapp.exe.manifest
# ├── pyiboot01_bootstrap.pyc
# ├── pyimod01_os_path.pyc
# ├── ...
# └── PYZ-00.pyz_extracted/
# ├── __main__.pyc
# ├── module1.pyc
# └── ...
```

### 示例 2: 处理加密的 PYZ 归档 / Example 2: Handling encrypted PYZ archives

如果遇到加密的 PYZ 归档，脚本会自动检测并以 `.pyc.encrypted` 扩展名保存文件，供后续处理。

If encrypted PYZ archives are encountered, the script automatically detects and saves files with `.pyc.encrypted` extension for subsequent processing.

## 常见问题解答 / FAQ

### Q1: 为什么建议使用相同版本的 Python 运行脚本？
**A:** 不同版本的 Python 可能使用不同的字节码格式，这可能导致解包 `.pyc` 文件时出现错误。使用相同版本可以确保最佳兼容性。

**Q1: Why is it recommended to run the script with the same Python version?**
**A:** Different Python versions may use different bytecode formats, which can cause errors when unpacking `.pyc` files. Using the same version ensures optimal compatibility.

### Q2: 如何反编译提取出的 `.pyc` 文件？
**A:** 您可以使用以下工具之一：
- **uncompyle6** - 支持 Python 2.7 和 3.2-3.8
- **decompyle3** - 支持 Python 3.7-3.8
- **pycdc** - 支持多种 Python 版本

**Q2: How to decompile extracted `.pyc` files?**
**A:** You can use one of the following tools:
- **uncompyle6** - Supports Python 2.7 and 3.2-3.8
- **decompyle3** - Supports Python 3.7-3.8
- **pycdc** - Supports multiple Python versions

### Q3: 脚本报错 "Unsupported pyinstaller version" 怎么办？
**A:** 这表示您的可执行文件使用的是脚本不支持的 PyInstaller 版本。请检查 PyInstaller 版本或考虑使用其他解包工具。

**Q3: What to do if the script reports "Unsupported pyinstaller version"?**
**A:** This indicates that your executable uses a PyInstaller version not supported by the script. Check the PyInstaller version or consider using other unpacking tools.

## 版本历史 / Version History

### v1.8.1 (2025年12月20日 / December 20, 2025)
- 修复在3.x.x版本时无法运行的问题 / Fix the issue that prevented running in version 3.x.x
- 添加zh-cn语言支持 / Add zh-CN language support
- 使用 importlib 替代已弃用的 imp 模块 / Use importlib to replace deprecated imp module

### v1.8 (2017年4月28日 / April 28, 2017)
- 支持 PYZ 文件中的子目录 / Support for sub-directories in .pyz files
- 感谢 Moritz Kroll @ Avira Operations GmbH & Co. KG / Thanks to Moritz Kroll @ Avira Operations GmbH & Co. KG

### v1.7 (2017年3月13日 / March 13, 2017)
- 使脚本兼容 Python 2.6 / Made the script compatible with python 2.6

### v1.6 (2016年9月5日 / September 5, 2016)
- 支持 PyInstaller 3.2 / Added support for pyinstaller 3.2
- 提取未命名文件时使用随机名称 / Extractor will use a random name while extracting unnamed files
- 加密 PYZ 归档按原样转储 / For encrypted pyz archives it will dump the contents as is

### v1.5 (2016年3月1日 / March 1, 2016)
- 支持 PyInstaller 3.1 / Added support for pyinstaller 3.1

### v1.4 (2016年1月19日 / January 19, 2016)
- 修复写入 pyc 文件版本 >= 3.3 时的错误 / Fixed a bug when writing pyc files >= version 3.3

### v1.3 (2015年12月12日 / December 12, 2015)
- 支持 PyInstaller 3.0 正式版 / Added support for pyinstaller 3.0 final
- 兼容 Python 2.x 和 3.x / Script is compatible with both python 2.x & 3.x

### v1.2 (2015年9月12日 / September 12, 2015)
- 支持 PyInstaller 2.1 和 3.0 开发版 / Added support for pyinstaller 2.1 and 3.0 dev
- 代码清理 / Cleaned up code
- 更详细的输出 / Script is now more verbose
- 在专用子目录中提取可执行文件 / Executable extracted within a dedicated sub-directory

### v1.1 (2014年1月28日 / January 28, 2014)
- 首次发布 / First Release
- 仅支持 PyInstaller 2.0 / Supports only pyinstaller 2.0

## 许可证 / License

本项目根据 GNU General Public License (GPL) v3 许可证授权。

This project is licensed under the GNU General Public License (GPL) v3.

## 作者信息 / Author Information

### 原始作者 / Original Authors
- **Extreme Coders**
- 邮箱 / Email: extremecoders(at)hotmail(dot)com
- 网站 / Web: https://0xec.blogspot.com

### v1.8.1 修改者 / v1.8.1 Modifier
- **Liu Yu chen / 刘宇晨**
- 邮箱 / Email: liuyuchen032901@outlook.com

## 注意事项 / Notes

1. 本工具仅用于教育和合法逆向工程目的。
2. 请确保您有权分析和修改目标可执行文件。
3. 对于加密或混淆的可执行文件，可能需要额外步骤才能完全提取内容。

1. This tool is intended for educational and legitimate reverse engineering purposes only.
2. Ensure you have the right to analyze and modify the target executable.
3. For encrypted or obfuscated executables, additional steps may be required to fully extract content.

## 贡献指南 / Contribution Guidelines

欢迎提交问题和改进建议。由于原始作者已不再维护此项目，请通过修改者的邮箱联系。

Issues and improvement suggestions are welcome. Since the original author is no longer maintaining this project, please contact the modifier via email.
Loading