تحويل ملف بايثون إلى EXE على ويندوز باستخدام PyInstaller خطوة بخطوة

تحويل ملف بايثون py إلى EXE على ويندوز باستخدام PyInstaller خطوة بخطوة

كتبت برنامجًا ببايثون ويعمل لديك بشكل ممتاز، لكنك الآن تريد إرساله إلى شخص آخر أو تشغيله على جهاز ويندوز لا يحتوي على بايثون. هنا يظهر السؤال الذي يواجه كثيرًا من المبتدئين: كيف أحول ملف بايثون إلى EXE؟

من أشهر الأدوات لهذا الغرض PyInstaller. الأداة تجمع برنامجك مع مفسر بايثون والمكتبات والملفات المطلوبة في حزمة قابلة للتشغيل، ولذلك يستطيع المستخدم تشغيل النسخة المجمعة دون تثبيت بايثون أو تثبيت مكتبات المشروع واحدة واحدة.

في هذا الدرس سنحوّل ملف .py إلى ملف .exe على ويندوز خطوة بخطوة باستخدام PyInstaller، ثم نتوسع في أهم ما يحتاجه الباحث فعلًا بعد أول تحويل: الفرق بين --onefile و--onedir، تغيير اسم البرنامج، إضافة أيقونة، إخفاء نافذة CMD في البرامج الرسومية، إضافة ملفات JSON والصور، حل مشكلة pyinstaller is not recognized، وتشخيص البرامج التي تعمل قبل التحويل ثم تتوقف بعده.

{alertInfo} الخلاصة السريعة: على ويندوز، افتح Terminal داخل مجلد مشروعك، ثبّت PyInstaller، ثم استخدم python -m PyInstaller --onefile app.py. بعد اكتمال البناء ستجد الملف التنفيذي داخل مجلد dist.

{getToc} $title={محتوى المقال}

تحويل ملف بايثون إلى EXE في 4 خطوات سريعة

إذا كان لديك ملف بسيط باسم app.py وتريد النتيجة بسرعة، فهذه هي الخطوات الأساسية التي تحتاجها على ويندوز:

افتح CMD أو Terminal.
ثبّت PyInstaller.
انتقل إلى مجلد المشروع باستخدام cd.
ابنِ ملف EXE ثم افتح مجلد dist.

python -m pip install -U pyinstaller
cd C:\Path\To\Your\Project
python -m PyInstaller --onefile app.py

بعد نجاح البناء ستجد الملف هنا غالبًا:

dist\app.exe

{alertSuccess} إذا كان هدفك فقط تحويل ملف py إلى exe: هذا يكفي للمشروع البسيط. أكمل بقية الدرس عندما تحتاج إلى أيقونة، إخفاء CMD، ملفات خارجية، أو حل مشكلة في النسخة المجمعة.

ما هو PyInstaller؟

PyInstaller أداة لتحويل تطبيقات بايثون إلى حزم مستقلة نسبيًا عن بيئة التطوير. تقوم بتحليل ملف البداية، وتتبع imports والاعتماديات، وتجمع مفسر بايثون والملفات الثنائية والمكتبات المطلوبة في ناتج يمكنك توزيعه على المستخدم.

المهم أن تفهم أن PyInstaller لا «يحوّل بايثون إلى C++» ولا يعيد كتابة مشروعك كلغة أخرى. هو يقوم بعملية bundling أو freezing: يجمع ما يحتاجه البرنامج ليعمل خارج بيئة التطوير المعتادة.

هل يحتاج الجهاز الآخر إلى تثبيت بايثون؟

عادةً لا. هذه إحدى الفوائد الأساسية لـPyInstaller: النسخة المجمعة تحتوي على المكونات التي يحتاجها التطبيق لتشغيل كود بايثون والمكتبات التي اكتشفها أثناء البناء.

لكن هذا لا يعني أن أي ملف EXE سيعمل على أي نظام تشغيل. PyInstaller ليس cross-compiler. إذا كنت تريد ملف EXE لويندوز، ابنه على ويندوز. وإذا أردت تطبيقًا لنظام آخر، تحتاج عادةً إلى تنفيذ عملية البناء على ذلك النظام.

هل PyInstaller يحول أي مشروع إلى EXE بضغطة واحدة؟

المشاريع البسيطة غالبًا تعمل بسرعة، لكن المشاريع التي تستخدم imports ديناميكية، ملفات خارجية، مكتبات رسومية أو DLLs قد تحتاج خيارات إضافية. لذلك سنبدأ ببرنامج صغير، ثم نضيف التعقيد تدريجيًا.

المتطلبات قبل تحويل ملف بايثون إلى EXE

قبل تثبيت PyInstaller تأكد من ثلاثة أمور:

بايثون مثبت ويعمل من Terminal أو CMD.
البرنامج الأصلي يعمل بدون أخطاء قبل محاولة تجميعه.
مكتبات المشروع مثبتة في نفس البيئة التي ستستخدمها في البناء.

اختبر بايثون:

python --version

إذا كنت تستخدم مشغل بايثون في ويندوز يمكنك أيضًا تجربة:

py --version

يفضل استخدام بيئة افتراضية للمشروع

يمكنك تثبيت PyInstaller عالميًا، لكن في المشاريع الحقيقية يفضل إنشاء بيئة افتراضية venv للمشروع. هذا يجعل PyInstaller يرى مكتبات المشروع المطلوبة بدل أن يعمل في بيئة ممتلئة بحزم لا علاقة لها بالتطبيق.

أنشئ البيئة:

python -m venv .venv

ثم فعّلها في Command Prompt:

.venv\Scripts\activate

بعد التفعيل ثبت مكتبات مشروعك ثم PyInstaller داخل البيئة نفسها.

تثبيت PyInstaller على ويندوز

استخدم الأمر:

python -m pip install -U pyinstaller

استخدام python -m pip مفيد لأنه يربط عملية التثبيت بنفس مفسر بايثون الذي تستخدمه حاليًا. وإذا كانت أوامر التثبيت جديدة عليك، راجع شرح pip وتثبيت مكتبات بايثون.

الانتقال إلى مجلد ملف بايثون باستخدام cd

قبل تشغيل أمر PyInstaller يجب أن يكون Terminal داخل المجلد الذي يحتوي ملفك، مثل app.py. استخدم أمر cd مع مسار المشروع:

cd C:\Users\YourName\Desktop\MyProject

ثم تأكد أن الملف موجود باستخدام:

dir

إذا ظهر app.py في القائمة، فأنت في المكان الصحيح ويمكنك تنفيذ أوامر البناء. هذه الخطوة البسيطة تمنع كثيرًا من أخطاء «الملف غير موجود» الناتجة عن تشغيل PyInstaller من مجلد مختلف.

كيف أتأكد أن PyInstaller مثبت؟

جرّب:

pyinstaller --version

إذا ظهر رقم الإصدار فالتثبيت صحيح.

وإذا ظهر أن الأمر غير معروف، لا تتوقف هنا. شغّل PyInstaller كـmodule:

python -m PyInstaller --version

لاحظ أن اسم الـmodule هنا PyInstaller بحروفه كما هو.

حل مشكلة pyinstaller is not recognized

إذا ظهرت رسالة قريبة من:

'pyinstaller' is not recognized as an internal or external command

فهذا لا يعني بالضرورة أن PyInstaller غير مثبت. قد يكون مجلد Scripts غير موجود داخل متغير PATH، أو قد تكون ثبتت الأداة في بيئة مختلفة.

الحل الأبسط والأكثر وضوحًا:

python -m PyInstaller app.py

بهذه الطريقة تطلب من مفسر بايثون نفسه تشغيل module المثبتة في بيئته، ولا تعتمد على وجود الأمر pyinstaller في PATH.

إنشاء برنامج بسيط للتجربة

أنشئ ملفًا باسم app.py:

name = input("اكتب اسمك: ")

print(
    f"مرحبًا {name} من بايثون العرب"
)

input(
    "اضغط Enter للخروج..."
)

شغله أولًا بالطريقة العادية:

python app.py

لا تنتقل إلى PyInstaller إذا كان البرنامج نفسه لا يعمل. حل أخطاء البرنامج أولًا، ثم ابدأ التجميع.

تحويل ملف بايثون إلى EXE لأول مرة

وأنت داخل المجلد الذي يحتوي app.py نفذ:

python -m PyInstaller app.py

PyInstaller سيحلل التطبيق ثم ينشئ ملفات ومجلدات جديدة داخل المشروع.

أين أجد ملف EXE بعد PyInstaller؟

بعد نجاح البناء ستلاحظ غالبًا:

project/
│
├── app.py
├── app.spec
├── build/
└── dist/
    └── app/
        ├── app.exe
        └── _internal/

مجلد dist هو أهم مكان بالنسبة للمستخدم النهائي. النسخة التي تريد تجربتها أو توزيعها موجودة داخله.

ما الفرق بين build وdist وملف spec؟

العنصر	وظيفته
`build`	ملفات وسيطة يستخدمها PyInstaller أثناء عملية البناء. ليست عادةً ما توزعه للمستخدم.
`dist`	الناتج النهائي الذي تختبره وتوزعه.
`app.spec`	ملف إعداد يصف طريقة بناء التطبيق، ويصبح مفيدًا عندما تحتاج تخصيصات متقدمة.

مكان ملف EXE بعد PyInstaller وشرح build وdist وملف spec

لماذا لم أحصل على ملف EXE واحد؟

الوضع الافتراضي في PyInstaller هو onedir. أي أنه يبني مجلدًا يحتوي الملف التنفيذي والاعتماديات المصاحبة له.

وهذا طبيعي، وليس خطأ.

تحويل بايثون إلى ملف EXE واحد باستخدام --onefile

إذا أردت ملفًا تنفيذيًا واحدًا، استخدم:

python -m PyInstaller --onefile app.py

بعد انتهاء البناء ستجد:

dist/
└── app.exe

هذه هي الصيغة التي يبحث عنها كثير من المستخدمين عند كتابة «تحويل py إلى exe» أو «تحويل برنامج بايثون إلى ملف واحد».

الفرق بين --onefile و--onedir

لا تفترض أن onefile أفضل دائمًا. لكل وضع استخدام مناسب.

المقارنة	onedir	onefile
شكل الناتج	مجلد يحتوي EXE وملفات الدعم.	ملف تنفيذي واحد.
سهولة الإرسال	تحتاج إرسال المجلد كاملًا.	أسهل لأن لديك ملفًا واحدًا.
التشخيص	غالبًا أسهل أثناء التطوير.	قد يكون تتبع بعض مشاكل الملفات أصعب.
بداية التشغيل	لا يحتاج إلى فك حزمة onefile في كل تشغيل.	يفك ملفات الدعم في مجلد مؤقت أثناء التشغيل، لذلك قد تكون البداية أبطأ في بعض التطبيقات.

نصيحتي للمبتدئ: اجعل البرنامج يعمل أولًا في onedir. بعد أن تتأكد أن كل المكتبات والملفات الخارجية موجودة، انتقل إلى --onefile إذا كنت تحتاج ملفًا واحدًا.

الفرق بين PyInstaller onefile وonedir عند تحويل ملف بايثون إلى EXE

تغيير اسم ملف EXE باستخدام --name

إذا كان الملف اسمه app.py لكنك تريد الناتج باسم مختلف:

python -m PyInstaller --onefile --name ExpenseTracker app.py

ستحصل على ملف قريب من:

dist\ExpenseTracker.exe

إضافة أيقونة إلى ملف EXE

جهز أيقونة ويندوز بصيغة .ico، مثل:

app.ico

ثم:

python -m PyInstaller --onefile --icon=app.ico app.py

من الأفضل وضع ملف الأيقونة داخل مجلد المشروع أو كتابة مساره الكامل إذا كان في مكان آخر.

لماذا لا تظهر الأيقونة الجديدة مباشرة؟

إذا بنيت ملفًا بنفس الاسم عدة مرات، قد يحتفظ ويندوز بصورة قديمة في icon cache. تأكد أولًا أن أمر البناء استخدم ملف .ico الصحيح، ثم جرّب تغيير اسم EXE أو تحديث عرض المجلد قبل افتراض أن PyInstaller تجاهل الأيقونة.

إخفاء نافذة CMD عند تشغيل برنامج بايثون

إذا كان برنامجك رسوميًا مثل تطبيق مبني بـTkinter أو PyQt ولا يحتاج إلى console، يمكنك استخدام:

python -m PyInstaller --onefile --noconsole app.py

والخيار --windowed يؤدي الغرض نفسه على ويندوز:

python -m PyInstaller --onefile --windowed app.py

لا تستخدم --noconsole مع برنامج يعتمد على input وprint

هذه نقطة مهمة جدًا. البرنامج الذي يعمل من Terminal ويستخدم:

name = input("Name: ")
print(name)

يحتاج إلى console. إذا بنيته باستخدام --noconsole فقد تختفي واجهة الإدخال والإخراج التي يعتمد عليها.

استخدم إخفاء CMD للبرامج الرسومية التي لها نافذتها الخاصة، وليس كخيار تضعه تلقائيًا في كل مشروع.

مثال بسيط لبرنامج رسومي

أنشئ gui_app.py:

import tkinter as tk


root = tk.Tk()
root.title("بايثون العرب")
root.geometry("350x180")

label = tk.Label(
    root,
    text="تم تشغيل البرنامج بنجاح",
    font=("Arial", 16)
)

label.pack(
    pady=50
)

root.mainloop()

شغله أولًا:

python gui_app.py

ثم ابنِ النسخة بدون نافذة console:

python -m PyInstaller --onefile --noconsole gui_app.py

أمر احترافي يجمع الاسم والأيقونة وonefile

python -m PyInstaller --onefile --noconsole --name ArabPythonApp --icon=app.ico gui_app.py

هذا مثال مناسب لبرنامج رسومي بسيط. لا تنسَ أن إضافة الملفات الخارجية تحتاج خطوة مستقلة كما سنشرح الآن.

مشكلة: EXE يعمل لكن الصور أو JSON لا تظهر

PyInstaller يستطيع اكتشاف imports، لكنه لا يعرف تلقائيًا أن مشروعك يحتاج كل ملف صورة أو JSON أو قاعدة بيانات أو قالب HTML موجود بجانب الكود.

لنفترض أن لديك:

project/
│
├── app.py
└── config.json

والكود يقرأ الملف. إذا لم تضفه إلى الحزمة، قد يعمل البرنامج من المصدر ثم يفشل بعد التحويل.

إضافة ملف باستخدام --add-data

في الإصدارات الحديثة من PyInstaller استخدم الصيغة:

python -m PyInstaller --onefile --add-data="config.json:." app.py

الجزء قبل النقطتين هو الملف المصدر، والجزء بعدهما هو مكانه داخل الحزمة. النقطة . تعني جذر الحزمة.

{alertInfo} معلومة مهمة: قد تجد شروحات ويندوز قديمة تستخدم الفاصلة المنقوطة ; داخل --add-data. PyInstaller الحديث يدعم صيغة النقطتين source:dest على ويندوز، وهي الصيغة الموحدة الموصى بها حاليًا.

إضافة مجلد صور كامل

إذا كان لديك:

assets/
├── logo.png
├── banner.png
└── icon.png

أضف المجلد:

python -m PyInstaller --onefile --add-data="assets:assets" app.py

الطريقة الصحيحة للوصول إلى ملف مرفق بعد التحويل

المشكلة ليست دائمًا في إضافة الملف؛ أحيانًا المسار داخل الكود نفسه غير مناسب. من الطرق الحديثة والبسيطة استخدام __file__ مع pathlib.

لملف config.json موضوع بجانب ملف البرنامج:

from pathlib import Path


base_dir = Path(__file__).resolve().parent
config_path = base_dir / "config.json"

print(config_path)

PyInstaller يضبط __file__ داخل التطبيق المجمّع بحيث يمكن استخدام هذا الأسلوب للعثور على الملفات التي وضعتها في الموقع المتوقع داخل الحزمة.

ملف داخل الحزمة أم ملف بجانب EXE؟ اختر المسار الصحيح

نتائج البحث عن مشاكل PyInstaller تتكرر فيها نقطة مهمة: ليست كل الملفات الخارجية من النوع نفسه. قبل اختيار طريقة المسار، حدد أين يفترض أن يعيش الملف بعد التحويل.

نوع الملف	المكان المناسب	طريقة الوصول المقترحة
صورة، قالب أو JSON ثابت مضمّن مع التطبيق	داخل حزمة PyInstaller باستخدام `--add-data`	مسار مبني على `__file__`
ملف إعدادات أو قاعدة بيانات تريد أن يعدّلها المستخدم	بجانب ملف `.exe` أو داخل مجلد بيانات مخصص للمستخدم	مسار مبني على `sys.executable` إذا كان المطلوب تحديد مجلد EXE نفسه
ملف يعتمد على المجلد الذي شغّل المستخدم التطبيق منه	Current Working Directory	`Path.cwd()` عند الحاجة المقصودة لذلك

إذا أردت مثلًا قراءة ملف قابل للتعديل اسمه settings.json موجود بجانب ملف EXE، يمكنك تحديد مجلد الملف التنفيذي هكذا:

from pathlib import Path
import sys

if getattr(sys, "frozen", False):
    app_dir = Path(sys.executable).resolve().parent
else:
    app_dir = Path(__file__).resolve().parent

settings_path = app_dir / "settings.json"
print(settings_path)

{alertInfo} الفرق المهم: استخدم __file__ عادةً للموارد التي ضمّنتها مع التطبيق، واستخدم sys.executable عندما تريد معرفة مكان ملف EXE الذي شغّله المستخدم فعليًا. وإذا كانت المشكلة مرتبطة بمجلد العمل الحالي أو تركيب المسارات، راجع شرح التعامل مع الملفات والمجلدات والمسارات في بايثون.

هل ما زلت أحتاج sys._MEIPASS؟

ستجد في شروحات كثيرة دالة مخصصة تفحص sys._MEIPASS. المتغير ما زال موجودًا في تطبيقات PyInstaller، لكن توثيق PyInstaller الحديث يوضح أن __file__ أصبح الطريقة المفضلة عادةً لتحديد الملفات المرفقة بالنسبة إلى ملف البرنامج.

استخدم sys._MEIPASS عندما تكون لديك حاجة محددة لفهم مسار الحزمة المؤقت أو التمييز بين التشغيل المجمّع والعادي، لكن لا تبدأ به تلقائيًا إذا كان __file__ يحل المشكلة ببساطة.

مشكلة: ModuleNotFoundError بعد تحويل البرنامج

إذا كان التطبيق يعمل عند تشغيل app.py لكنه يظهر عند تشغيل EXE:

ModuleNotFoundError: No module named 'example_module'

فابدأ بهذه الأسئلة:

هل المكتبة مثبتة داخل البيئة التي بنيت منها التطبيق؟
هل import مكتوبة بصورة يستطيع PyInstaller تحليلها؟
هل المكتبة تستورد modules ديناميكيًا وقت التشغيل؟

في بعض الحالات الديناميكية تحتاج إلى تعريف hidden import:

python -m PyInstaller --onefile --hidden-import=example_module app.py

لا تضف --hidden-import عشوائيًا لكل مكتبة. استخدمه عندما يثبت التشخيص أن PyInstaller لم يكتشف module مطلوبة. وإذا كانت المشكلة في الاستيراد نفسه، راجع شرح import واستيراد المكتبات والملفات داخل المشروع.

ماذا لو كانت مكتبة كاملة تحتوي على submodules وبيانات؟

يوفر PyInstaller خيارات مثل --collect-all لحالات محددة:

python -m PyInstaller --onefile --collect-all package_name app.py

لكن هذا قد يزيد حجم الناتج. الأفضل دائمًا فهم ما ينقص التطبيق بدل جمع كل شيء بدون سبب.

EXE يفتح ثم يغلق مباشرة: كيف أعرف الخطأ؟

إذا كان التطبيق console، لا تفتحه بالنقر المزدوج فقط أثناء التشخيص. افتح CMD داخل مجلد dist وشغل الملف:

app.exe

عندها ستبقى رسائل الخطأ ظاهرة ويمكنك قراءة Traceback. وإذا لم تكن معتادًا على معالجة الأخطاء، راجع شرح try وexcept والتعامل مع الأخطاء في بايثون.

إذا كان تطبيقك مبنيًا بـ--noconsole وأنت في مرحلة إصلاح مشكلة، أعد بناء نسخة console مؤقتًا بدون هذا الخيار. رؤية الخطأ أهم من إخفاء النافذة أثناء التطوير.

لماذا EXE يعمل على جهازي ولا يعمل على جهاز آخر؟

هذه المشكلة لها عدة أسباب محتملة، لذلك لا يوجد أمر واحد يصلحها كلها.

1. بنيت البرنامج لنظام مختلف

PyInstaller ليس cross-compiler. ملف ويندوز يجب بناؤه على ويندوز إذا كان هدفك إنشاء تطبيق ويندوز.

2. ملف خارجي غير مرفق

قد توجد صورة أو قاعدة بيانات أو ملف إعدادات على جهازك في مسار يعرفه التطبيق، لكنها غير موجودة مع النسخة التي أرسلتها.

3. import ديناميكية لم تُجمع

شغل EXE من CMD واقرأ الخطأ. إذا كانت module مفقودة فعلًا، عالج import أو استخدم hook أو --hidden-import عند الحاجة.

4. تعتمد على ملف موجود في Current Working Directory

لا تفترض أن المستخدم سيشغل التطبيق من نفس المجلد الذي تتوقعه. فرق مهم بين مسار الملف التنفيذي، ومجلد العمل الحالي، ومسار الملفات المرفقة.

5. مكتبة أو DLL لها متطلبات خاصة

بعض المكتبات التي تعتمد على ملفات ثنائية أو برامج خارجية تحتاج إعدادًا خاصًا. هنا تصبح سجلات PyInstaller وملف spec والـhooks أكثر أهمية.

كيف أختبر EXE قبل إرساله للناس؟

لا تعتبر نجاح البناء دليلًا كافيًا. اختبر النسخة داخل dist كأنك مستخدم جديد.

انقل الناتج إلى مجلد مختلف.
اختبر فتح البرنامج من النقر المزدوج ومن CMD إذا كان console.
جرّب كل شاشة أو وظيفة تعتمد على ملفات خارجية.
اختبر حفظ البيانات وإعادة فتح التطبيق.
جرّبه على جهاز ويندوز آخر أو بيئة نظيفة إن كان التطبيق مهمًا.

لماذا حجم ملف EXE كبير؟

قد يكون ملف بايثون الأصلي بضعة كيلوبايت بينما EXE يصبح عشرات الميجابايت. هذا طبيعي في كثير من المشاريع لأن PyInstaller لا يضع كودك وحده داخل الملف؛ فهو يجمع أيضًا مفسر بايثون والمكتبات والملفات الثنائية اللازمة.

ويزداد الحجم كثيرًا مع مكتبات مثل NumPy وPandas ومكتبات الواجهات الرسومية أو تعلم الآلة.

هل --onefile يقلل حجم البرنامج؟

ليس هذا هو الهدف الأساسي منه. --onefile يجعل التوزيع في ملف واحد، لكنه لا يعني أن كل الاعتماديات اختفت. هي موجودة داخل الحزمة ويتم استخراج ما يلزم أثناء التشغيل.

لماذا onefile قد يتأخر عند التشغيل؟

في وضع onefile يحتاج bootloader إلى استخراج ملفات الدعم إلى مجلد مؤقت عند بدء التشغيل، ثم يبدأ التطبيق. في البرامج الكبيرة قد يلاحظ المستخدم تأخيرًا أكبر مقارنة بـonedir.

إذا كانت سرعة البدء مهمة أكثر من وجود ملف واحد، اختبر onedir بدل افتراض أن onefile هو الشكل الأفضل دائمًا.

هل يمكن حذف build وملف spec بعد إنشاء EXE؟

يمكنك حذف build إذا لم تعد تحتاج ملفات البناء الوسيطة، وسيتم إنشاؤه مجددًا عند البناء التالي.

أما ملف .spec فمن الأفضل الاحتفاظ به إذا بدأت تخصيص مشروعك، لأنه قد يصبح وصفًا متكررًا لطريقة البناء. في المشاريع البسيطة تستطيع إعادة توليده، لكن في المشاريع المعقدة قد يحتوي إعدادات مهمة.

إعادة بناء التطبيق بعد تعديل الكود

بعد تغيير app.py يجب تشغيل PyInstaller مرة أخرى. مثال:

python -m PyInstaller --onefile --noconfirm app.py

يمكن استخدام --clean عندما تريد تنظيف cache PyInstaller وملفات مؤقتة قبل البناء:

python -m PyInstaller --clean --noconfirm --onefile app.py

أمر كامل لبرنامج رسومي مع أيقونة وملف JSON

python -m PyInstaller --clean --noconfirm --onefile --noconsole --name ExpenseTracker --icon=app.ico --add-data="config.json:." app.py

لا تنسخ هذا الأمر بدون فهمه. إذا كان برنامجك console احذف --noconsole. وإذا لم يكن لديك JSON احذف --add-data. الأمر الصحيح هو الذي يطابق مشروعك.

ماذا يفعل كل خيار في الأمر؟

الخيار	الوظيفة
`--clean`	ينظف cache وملفات PyInstaller المؤقتة قبل البناء.
`--noconfirm`	يسمح باستبدال مجلدات الناتج دون سؤال التأكيد المعتاد.
`--onefile`	ينشئ ملفًا تنفيذيًا واحدًا.
`--noconsole`	يبني تطبيقًا بدون console على ويندوز؛ مناسب للواجهات الرسومية التي لا تعتمد على stdin/stdout.
`--name`	يحدد اسم التطبيق الناتج.
`--icon`	يحدد أيقونة التطبيق.
`--add-data`	يضيف ملفات أو مجلدات بيانات إلى الحزمة.

مشكلة الأيقونة: icon file not found

إذا لم يجد PyInstaller ملف الأيقونة، تحقق من أنك داخل المجلد الصحيح:

dir

أو مرر مسارًا واضحًا بين علامات اقتباس:

python -m PyInstaller --onefile --icon="C:\MyProject\app.ico" app.py

علامات الاقتباس مهمة خصوصًا إذا كان المسار يحتوي على مسافات.

مشكلة FileNotFoundError بعد التحويل

إذا ظهر:

FileNotFoundError: [Errno 2] No such file or directory

فاسأل سؤالين منفصلين:

هل أضفت الملف إلى الحزمة أصلًا باستخدام --add-data أو spec؟
هل الكود يبحث عنه بالنسبة إلى المسار الصحيح؟

إضافة الملف وحدها لا تصلح مسارًا خاطئًا، وتصحيح المسار وحده لا يضيف ملفًا لم يدخل الحزمة.

مشكلة hidden imports: كيف أشخصها بدل التخمين؟

ابنِ نسخة onedir واحتفظ بالـconsole، ثم شغل التطبيق من CMD. اقرأ اسم module المفقودة. بعد ذلك راجع طريقة استيراد المكتبة؛ بعض الحزم توفر hooks جاهزة، وبعض الحالات تحتاج --hidden-import أو إعدادًا في ملف spec.

لا تجعل حل كل مشكلة هو إضافة عشرات hidden imports، لأن ذلك يزيد التعقيد والحجم وقد يخفي السبب الحقيقي.

ما هو ملف spec ومتى أحتاجه؟

عند تنفيذ PyInstaller لأول مرة ينشئ ملفًا مثل:

app.spec

هذا الملف عبارة عن كود إعداد يصف Analysis والملفات والخيارات والناتج. في المشاريع البسيطة لن تحتاج إلى تحريره يدويًا.

يصبح مفيدًا عندما تحتاج:

إضافة مجموعة كبيرة أو معقدة من ملفات البيانات.
جمع binaries أو DLLs خاصة.
إضافة hooks أو hidden imports متعددة بصورة ثابتة.
الحفاظ على وصف بناء متكرر للمشروع.

تشغيل البناء من ملف spec

بعد إعداد الملف:

python -m PyInstaller app.spec

لاحظ أن كثيرًا من خيارات command line لا تعمل بنفس الطريقة عندما تبني من spec؛ لأن الإعدادات أصبحت مسجلة داخل الملف نفسه.

هل PyInstaller يحمي الكود من السرقة؟

لا تعتبر تحويل المشروع إلى EXE وسيلة لحماية المصدر بشكل كامل. PyInstaller يجمع bytecode وموارد واعتماديات، ويمكن للمتخصصين تحليل الحزمة واستخراج أجزاء منها أو إعادة بناء قدر من المنطق.

إذا كان لديك سر حقيقي مثل API key أو كلمة مرور، لا تضعه داخل التطبيق وتفترض أن EXE يجعله آمنًا. الأسرار الحساسة تحتاج تصميمًا أمنيًا مختلفًا، مثل تخزينها في خادم وعدم توزيعها على العميل أصلًا.

هل يمكن تشغيل EXE على جهاز لا توجد فيه مكتبات المشروع؟

نعم، هذا هو الهدف من bundling. إذا تم جمع المكتبات بصورة صحيحة، لا يحتاج المستخدم إلى تنفيذ pip install لكل مكتبة.

لكن إذا تعتمد مكتبتك على ملفات خارجية أو برامج أخرى على النظام لم يجمعها PyInstaller، فقد تبقى متطلبات إضافية. لذلك اختبار جهاز نظيف مهم قبل التوزيع الحقيقي.

هل يمكن تحويل برنامج بايثون على لينكس إلى EXE لويندوز؟

ليس مباشرة باستخدام PyInstaller كأنه cross-compiler. لبناء تطبيق ويندوز شغل PyInstaller داخل بيئة ويندوز، سواء جهازًا فعليًا أو بيئة ويندوز مناسبة للبناء.

هل يعمل EXE على 32-bit و64-bit؟

ناتج PyInstaller يتأثر ببيئة البناء ومفسر بايثون والهندسة التي تستخدمها. إذا كنت تستهدف أجهزة محددة، ابنِ واختبر على بيئة مطابقة قدر الإمكان بدل افتراض أن ملفًا واحدًا سيغطي كل التركيبات القديمة والجديدة.

لماذا قد يحذر برنامج الحماية من EXE جديد؟

قد تتعامل بعض برامج الحماية بحذر مع ملفات تنفيذية جديدة أو غير موقعة، وخصوصًا تطبيقات onefile التي تفك ملفات الدعم مؤقتًا عند التشغيل. لا تتجاهل أي تحذير، لكن لا تفترض أيضًا أن التحذير وحده يثبت وجود مشكلة في كودك.

إذا كان البرنامج لك وتأكدت من مصدر الكود، ابدأ ببناء نظيف وبأحدث إصدار مناسب من PyInstaller، واختبر أيضًا وضع onedir. وللتوزيع العام، يكون توقيع الكود ورفع بلاغ False Positive إلى شركة الحماية عند الحاجة أفضل من مطالبة المستخدمين بتعطيل الحماية.

{alertWarning} لا تعالج التحذير بإيقاف Windows Defender أو تعطيل الحماية. افحص سبب التحذير أولًا، وتأكد من أن بيئة البناء والكود والمكتبات التي تستخدمها موثوقة.

أخطاء شائعة عند تحويل بايثون إلى EXE

1. استخدام --onefile من أول محاولة

ابدأ بـonedir إذا كان المشروع معقدًا. حل المشاكل أولًا ثم انتقل إلى onefile.

2. إخفاء CMD قبل اكتمال الاختبار

إذا استخدمت --noconsole مبكرًا قد تخفي Traceback الذي تحتاجه لفهم المشكلة.

3. نسيان الملفات الخارجية

وجود config.json بجانب الكود لا يعني أنه سيدخل الحزمة تلقائيًا.

4. استخدام مسارات مطلقة من جهاز المطور

مسار مثل:

C:\Users\Ali\Desktop\Project\config.json

لن يوجد غالبًا على جهاز المستخدم. اربط موارد الحزمة بمسار مناسب مثل __file__، أو استخدم مكان تخزين المستخدم عندما تكون البيانات قابلة للتعديل.

5. توزيع مجلد onedir ناقصًا

إذا بنيت الوضع الافتراضي، لا ترسل app.exe وحده من داخل المجلد وتتجاهل الملفات المرافقة. أرسل مجلد التوزيع كاملًا.

6. اعتبار نجاح عملية البناء نجاحًا للتطبيق

قد يكتب PyInstaller عبارة نجاح بينما التطبيق نفسه يفشل عند فتح ملف أو import ديناميكية. الاختبار النهائي جزء من عملية البناء.

حل أخطاء PyInstaller الشائعة بعد تحويل ملف بايثون إلى EXE

قائمة فحص قبل نشر ملف EXE

البرنامج الأصلي يعمل من نفس البيئة.
PyInstaller مثبت داخل بيئة المشروع.
اختبرت أولًا وضع onedir.
كل ملفات الصور وJSON والقوالب مضافة.
المسارات لا تعتمد على مجلد جهازك الشخصي.
جربت كل الوظائف الأساسية من نسخة dist.
لم تستخدم noconsole قبل التأكد من عدم حاجتك للـconsole.
جربت الملف على جهاز آخر إذا كنت ستوزعه على المستخدمين.

أوامر PyInstaller الأكثر استخدامًا

المطلوب	الأمر
بناء عادي onedir	`python -m PyInstaller app.py`
ملف EXE واحد	`python -m PyInstaller --onefile app.py`
تغيير الاسم	`python -m PyInstaller --onefile --name MyApp app.py`
إضافة أيقونة	`python -m PyInstaller --onefile --icon=app.ico app.py`
إخفاء console للبرنامج الرسومي	`python -m PyInstaller --onefile --noconsole app.py`
إضافة ملف	`python -m PyInstaller --onefile --add-data="config.json:." app.py`
إضافة hidden import	`python -m PyInstaller --onefile --hidden-import=module_name app.py`
تنظيف ثم إعادة البناء	`python -m PyInstaller --clean --noconfirm --onefile app.py`

هل يمكن تحويل Python إلى EXE بواجهة رسومية؟

نعم. إذا كنت لا تريد كتابة خيارات PyInstaller يدويًا، توجد أداة auto-py-to-exe التي توفر واجهة رسومية مبنية فوق PyInstaller. يمكن تثبيتها وتشغيلها هكذا:

python -m pip install auto-py-to-exe
auto-py-to-exe

من الواجهة تختار ملف .py، وتحدد One File أو One Directory، وتختار Console أو Window Based، ثم تضيف الأيقونة أو الملفات الإضافية إذا احتجت. ومع ذلك، أنصح بفهم أوامر PyInstaller الأساسية أولًا، لأن سطر الأوامر يجعل تشخيص الأخطاء أوضح عندما يفشل البناء أو التشغيل.

مصادر رسمية للتوسع

الخلاصة

تحويل ملف بايثون إلى EXE باستخدام PyInstaller يبدأ بأمر بسيط، لكن الحصول على تطبيق يمكن توزيعه باحتراف يتطلب فهم ما يحدث بعد ذلك. ابدأ بالتأكد من أن مشروعك يعمل داخل بيئة واضحة، ثبّت PyInstaller فيها، وابنِ نسخة onedir أولًا حتى يسهل التشخيص.

بعد نجاح التطبيق انتقل إلى --onefile إذا كنت تحتاج ملفًا واحدًا، واستخدم --name و--icon لتخصيص التطبيق. لا تستخدم --noconsole إلا للبرامج الرسومية التي لا تحتاج إلى Terminal، وأضف الصور وملفات JSON وغيرها باستخدام --add-data.

إذا فشل EXE بينما يعمل ملف بايثون، لا تعِد البناء عشوائيًا. شغّل النسخة من CMD، اقرأ Traceback، وحدد هل المشكلة في import مفقودة أو ملف بيانات أو مسار. هذه الطريقة أسرع من تجربة عشرات الخيارات بدون تشخيص.

{alertSuccess} القاعدة المهمة: PyInstaller لا يجعل البرنامج جاهزًا للتوزيع لأن أمر البناء انتهى فقط. النسخة الجيدة هي التي اختبرتها من داخل dist، نقلتها خارج مجلد التطوير، وتأكدت أن المكتبات والملفات والمسارات تعمل كما ستعمل عند المستخدم.

أسئلة شائعة

كيف أحول ملف بايثون إلى EXE على ويندوز؟

ثبت PyInstaller ثم استخدم python -m PyInstaller --onefile app.py. ستجد الملف التنفيذي النهائي داخل مجلد dist.

هل يعمل ملف EXE بدون تثبيت بايثون؟

نعم في الاستخدام المعتاد، لأن PyInstaller يجمع مفسر بايثون والاعتماديات المطلوبة مع التطبيق، لذلك لا يحتاج المستخدم إلى تثبيت بايثون ومكتبات المشروع يدويًا.

ما حل pyinstaller is not recognized؟

جرّب python -m PyInstaller --version ثم استخدم نفس الصيغة للبناء. المشكلة غالبًا مرتبطة بمجلد Scripts في PATH أو اختلاف بيئة التثبيت.

كيف أحول py إلى exe ملف واحد؟

استخدم الخيار --onefile: python -m PyInstaller --onefile app.py.

ما الفرق بين onefile وonedir؟

onedir ينشئ مجلدًا يحتوي EXE وملفات الدعم، وهو الوضع الافتراضي وغالبًا أسهل للتشخيص. onefile يجمع الحزمة في ملف واحد أسهل في الإرسال لكنه يحتاج إلى استخراج ملفات دعم عند التشغيل.

كيف أضيف أيقونة إلى EXE؟

جهز ملف .ico ثم استخدم --icon=app.ico أثناء البناء.

كيف أخفي نافذة CMD بعد تحويل البرنامج؟

للبرامج الرسومية استخدم --noconsole أو --windowed. لا تستخدمهما مع برنامج يعتمد على input() وprint() داخل console.

كيف أضيف ملف JSON أو صورة إلى PyInstaller؟

استخدم --add-data="source:destination"، مثل --add-data="config.json:."، ثم استخدم مسارًا مناسبًا في الكود مثل المسار المبني على __file__.

كيف أقرأ ملفًا موجودًا بجانب EXE بعد التحويل؟

إذا كان الملف خارجيًا وقابلًا للتعديل وموجودًا بجانب ملف EXE، فاستخدم مجلد Path(sys.executable).resolve().parent عندما يكون التطبيق مجمّعًا. أما الملفات التي أضفتها داخل الحزمة باستخدام --add-data فمن الأنسب عادةً الوصول إليها نسبةً إلى __file__.

هل يمكن تحويل ملف بايثون إلى EXE بدون كتابة أوامر PyInstaller يدويًا؟

نعم، يمكنك استخدام auto-py-to-exe كواجهة رسومية لـPyInstaller. لكنها لا تلغي الحاجة إلى فهم الفرق بين onefile وonedir والملفات المرفقة إذا ظهرت مشكلة بعد التحويل.

لماذا EXE لا يجد الصور والملفات؟

لأن الملفات غير البرمجية لا تدخل الحزمة دائمًا تلقائيًا، أو لأن الكود يستخدم مسارًا مرتبطًا بجهاز التطوير. أضف الموارد باستخدام --add-data وصحح طريقة تحديد المسار.

لماذا يظهر ModuleNotFoundError داخل EXE؟

قد تكون المكتبة مثبتة في بيئة مختلفة، أو PyInstaller لم يكتشف import ديناميكية. شغّل EXE من CMD لمعرفة اسم module، ثم عالج السبب أو استخدم --hidden-import عند الحاجة. ولتشخيص الخطأ نفسه راجع حل ModuleNotFoundError: No module named.

لماذا ملف EXE كبير جدًا؟

لأن الحزمة تحتوي على مفسر بايثون ومكتبات واعتماديات التطبيق، وليس الكود الخاص بك فقط. المشاريع التي تستخدم مكتبات كبيرة تنتج ملفات أكبر.

هل PyInstaller يحمي كود بايثون من الاستخراج؟

لا. لا تعتبر EXE وسيلة حماية كاملة للمصدر أو للأسرار. يمكن تحليل الحزم، لذلك لا تخزن مفاتيح حساسة داخل التطبيق على أساس أنها أصبحت مخفية.

هل يمكن بناء EXE لويندوز من لينكس باستخدام PyInstaller؟

PyInstaller ليس cross-compiler. لبناء تطبيق ويندوز استخدم بيئة ويندوز ثم اختبر الناتج على أجهزة ويندوز التي تستهدفها.

أين يوجد ملف EXE بعد انتهاء PyInstaller؟

يوجد الناتج داخل مجلد dist. في وضع onedir يكون داخل مجلد التطبيق، وفي onefile يظهر كملف EXE واحد داخل dist.