# التثبيت

قبل أن تبدأ، ستحتاج إلى إعداد بيئتك من خلال تثبيت الحزم المناسبة.

يُختبر `huggingface_hub` على **Python 3.10+**.

## التثبيت باستخدام pip

يُوصى بشدة بتثبيت `huggingface_hub` في [بيئة افتراضية](https://docs.python.org/3/library/venv.html). إذا لم تكن على دراية بالبيئات الافتراضية في بايثون، فاطّلع على هذا [الدليل](https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/). تُسهّل البيئة الافتراضية إدارة المشاريع المختلفة، وتساعد على تجنب مشاكل التوافق بين الاعتماديات.

ابدأ بإنشاء بيئة افتراضية في مجلد مشروعك:

```bash
python -m venv .venv
```

فعّل بيئة التشغيل الافتراضية. على أنظمة لينكس وماك أو إس:

```bash
source .venv/bin/activate
```

تفعيل بيئة افتراضية على نظام ويندوز:

```bash
.venv/Scripts/activate
```

الآن أنت مستعد لتثبيت `huggingface_hub` [من سجل PyPi](https://pypi.org/project/huggingface-hub/):

```bash
pip install --upgrade huggingface_hub
```

بعد الانتهاء، تأكد من أن [فحص التثبيت](#check-installation) يعمل بشكل صحيح.

### تثبيت التبعيات الاختيارية

بعض تبعيات `huggingface_hub` هي [اختيارية](https://setuptools.pypa.io/en/latest/userguide/dependency_management.html#optional-dependencies) لأنها غير مطلوبة لتشغيل الميزات الأساسية لـ `huggingface_hub`. ومع ذلك، قد لا تكون بعض ميزات `huggingface_hub` متاحة إذا لم يتم تثبيت التبعيات الاختيارية.

يمكنك تثبيت التبعيات الاختيارية عبر `pip`:
```bash
# Install dependencies for both torch-specific and MCP-specific features.
pip install 'huggingface_hub[mcp,torch]'
```

فيما يلي قائمة التبعيات الاختيارية في `huggingface_hub`:
- `fastai`، `torch`: التبعيات اللازمة لتشغيل الميزات الخاصة بالإطار.
- `dev`: التبعيات المساهمة في المكتبة. تتضمن `testing` (لتشغيل الاختبارات)، و`typing` (لتشغيل أداة فحص الأنواع)، و`quality` (لتشغيل أدوات التدقيق).

### التثبيت من المصدر

في بعض الحالات، يكون من المفيد تثبيت `huggingface_hub` مباشرةً من المصدر. وهذا يتيح لك استخدام أحدث إصدار على فرع `main` بدلاً من أحدث إصدار مستقر. يُعدّ إصدار `main` مفيدًا للبقاء على اطلاع بأحدث التطورات، على سبيل المثال إذا تم إصلاح خطأ برمجي منذ آخر إصدار رسمي ولم يتم إصدار نسخة جديدة بعد.

ومع ذلك، هذا يعني أن إصدار `main` قد لا يكون دائمًا مستقرًا. نسعى جاهدين للحفاظ على تشغيل إصدار `main`، وعادةً ما يتم حل معظم المشكلات خلال بضع ساعات أو يوم واحد. إذا واجهت مشكلة، فيرجى فتح مشكلة (Issue) حتى نتمكن من إصلاحها بشكل أسرع!

```bash
pip install git+https://github.com/huggingface/huggingface_hub
```

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

```bash
pip install git+https://github.com/huggingface/huggingface_hub@my-feature-branch
```

بعد الانتهاء، تأكد من أن [فحص التثبيت](#check-installation) يعمل بشكل صحيح.

### التثبيت القابل للتعديل

يتيح لك التثبيت من المصدر إعداد [تثبيت قابل للتحرير](https://pip.pypa.io/en/stable/topics/local-project-installs/#editable-installs). يُعد هذا خيار تثبيت متقدمًا إذا كنت تنوي المساهمة في `huggingface_hub` وتحتاج إلى اختبار التغييرات في الكود. يجب عليك استنساخ نسخة محلية من `huggingface_hub` على جهازك.

```bash
# First, clone repo locally
git clone https://github.com/huggingface/huggingface_hub.git

# Then, install with -e flag
cd huggingface_hub
pip install -e .
```

ستربط هذه الأوامر المجلد الذي استنسلت فيه المستودع بمسارات مكتبات Python الخاصة بك. سيبحث Python الآن داخل المجلد الذي استنسلت فيه بالإضافة إلى مسارات المكتبات المعتادة. على سبيل المثال، إذا كانت حزم Python لديك تُثبَّت عادةً في `./.venv/lib/python3.13/site-packages/`، فسيبحث Python أيضاً في المجلد الذي استنسلته `./huggingface_hub/`.

## تثبيت واجهة سطر أوامر Hugging Face 

استخدم مُثبِّلاتنا من سطر واحد لإعداد واجهة `hf` السطرية دون المساس ببيئة بايثون الخاصة بك:

على macOS و Linux:

```bash
curl -LsSf https://hf.co/cli/install.sh | bash
```

على نظام ويندوز:

```powershell
powershell -ExecutionPolicy ByPass -c "irm https://hf.co/cli/install.ps1 | iex"
```

لتحديث تثبيت قائم، شغّل `hf update` — حيث يكتشف الطريقة التي تم بها تثبيت `hf` (المثبّت المستقل، أو Homebrew، أو pip) وينفّذ الأمر المطابق.

## التثبيت باستخدام conda

إذا كنت أكثر إلمامًا به، يمكنك تثبيت `huggingface_hub` باستخدام [قناة conda-forge](https://anaconda.org/conda-forge/huggingface_hub):

```bash
conda install -c conda-forge huggingface_hub
```

بعد الانتهاء، تأكد من أن [فحص التثبيت](#check-installation) يعمل بشكل صحيح.

## التحقق من التثبيت

بعد التثبيت، تحقق من أن `huggingface_hub` يعمل بشكل صحيح عن طريق تنفيذ الأمر التالي:

```bash
python -c "from huggingface_hub import model_info; print(model_info('gpt2'))"
```

ستجلب هذه الأوامر معلومات من Hub حول نموذج [gpt2](https://huggingface.co/gpt2). يجب أن يبدو الناتج على النحو التالي:

```text
Model Name: gpt2
Tags: ['pytorch', 'tf', 'jax', 'tflite', 'rust', 'safetensors', 'gpt2', 'text-generation', 'en', 'doi:10.57967/hf/0039', 'transformers', 'exbert', 'license:mit', 'has_space']
Task: text-generation
```

## قيود ويندوز

بهدفنا المتمثل في ديمقراطية تعلم الآلة الجيد في كل مكان، بنينا `huggingface_hub` ليكون مكتبة تعمل عبر المنصات، وتحديداً لتعمل بشكل صحيح على أنظمة يونكس وأنظمة ويندوز. ومع ذلك، هناك بعض الحالات التي تكون فيها `huggingface_hub` محدودة عند تشغيلها على ويندوز. فيما يلي قائمة شاملة بالمشاكل المعروفة. يرجى إعلامنا إذا واجهت أي مشكلة غير موثقة من خلال فتح [مشكلة على Github](https://github.com/huggingface/huggingface_hub/issues/new/choose).

- يعتمد نظام التخزين المؤقت في `huggingface_hub` على الروابط الرمزية لتخزين الملفات التي تم تنزيلها بشكل فعال
من Hub. على نظام Windows، يجب تفعيل وضع المطوّر أو تشغيل سكربت الخاص بك بصلاحيات المسؤول لتفعيل الروابط الرمزية. إذا لم تكن مفعّلة، فإن نظام التخزين المؤقت لا يزال يعمل ولكن بطريقة غير مُحسّنة. يرجى قراءة قسم [قيود التخزين المؤقت](./guides/manage-cache#limitations) لمزيد من التفاصيل.
- يمكن أن تحتوي مسارات الملفات على المركز على أحرف خاصة (مثل `"path/to?/my/file"`). ويندوز
أكثر تقييدًا فيما يتعلق بـ [الأحرف الخاصة](https://learn.microsoft.com/en-us/windows/win32/intl/character-sets-used-in-file-names) مما يجعل من المستحيل تنزيل تلك الملفات على نظام ويندوز. نأمل أن يكون هذا حالة نادرة. يرجى التواصل مع مالك المستودع إذا كنت تعتقد أن هذا خطأ، أو التواصل معنا لإيجاد حل.

## الخطوات التالية

بمجرد تثبيت `huggingface_hub` بشكل صحيح على جهازك، قد ترغب في [إعداد متغيرات البيئة](package_reference/environment_variables) أو [الاطلاع على أحد أدلةنا](guides/overview) للبدء.