This document explains how to set up a local development environment for contributing to the g4f (GPT4Free) project. It covers repository cloning, dependency installation, testing, and development tools. For information about the overall project structure and code organization, see Project Structure. For guidance on implementing new providers, see Adding New Providers.
The following tools and software are required for g4f development:
| Requirement | Version | Purpose |
|---|---|---|
| Python | 3.10+ (3.8+ minimum) | Runtime environment for g4f package |
| Git | Latest | Version control |
| Google Chrome/Chromium | Latest | Browser automation via nodriver/zendriver (optional) |
| pip | Latest | Package installation and management |
| setuptools | Latest | Build system (included in requirements.txt) |
Python Version Compatibility:
requirements-min.txtSources: README.md91-96 requirements.txt16 setup.py37
<old_str>
Clone the g4f repository from GitHub:
The repository contains several key directories that are relevant to development:
| Directory | Purpose |
|---|---|
g4f/ | Main package source code |
etc/ | Development tools and scripts |
.github/workflows/ | CI/CD configuration |
docker/ | Dockerfile configurations |
scripts/ | Build and utility scripts |
For a complete directory structure overview, see Project Structure.
Sources: README.md166-172 <new_str>
Clone the g4f repository from GitHub:
The repository contains several key directories relevant to development:
| Directory | Purpose |
|---|---|
g4f/ | Main package source code (models, providers, client) |
g4f/Provider/ | Provider implementations |
g4f/Provider/needs_auth/ | Authenticated provider implementations |
etc/ | Development tools and scripts |
etc/unittest/ | Test suite modules |
.github/workflows/ | CI/CD configuration (unittest.yml, copilot.yml, build-packages.yml) |
docker/ | Dockerfile configurations |
scripts/ | Build and utility scripts |
For a complete directory structure overview, see Project Structure.
The .gitignore file excludes the following from version control:
| Ignored Path | Reason |
|---|---|
__pycache__/, *.pyc | Python bytecode |
dist/, *.egg-info/ | Build artifacts |
generated_media/ | Generated images, audio, video |
har_and_cookies/ | Authentication data (sensitive) |
node_modules/ | JavaScript dependencies |
site-packages/, lib64/, pyvenv.cfg | Virtual environment files |
container/ | Container runtime files |
.idea/ | IDE configuration |
Note: When developing, create generated_media/ and har_and_cookies/ directories locally for testing. These directories are used by the application but are not tracked in Git for security and size reasons.
Sources: README.md166-172 .gitignore1-13
Clone the g4f repository from GitHub:
The repository contains several key directories that are relevant to development:
| Directory | Purpose |
|---|---|
g4f/ | Main package source code |
etc/ | Development tools and scripts |
.github/workflows/ | CI/CD configuration |
docker/ | Dockerfile configurations |
scripts/ | Build and utility scripts |
For a complete directory structure overview, see Project Structure.
Sources: README.md166-172
It is recommended to use a Python virtual environment to isolate development dependencies:
After activation, your shell prompt should show (venv) indicating the virtual environment is active.
Sources: setup.py1-183
The project provides three dependency configuration files for different use cases:
Dependency File Comparison:
| File | Dependencies | Use Case |
|---|---|---|
requirements-min.txt | Not shown in sources (referenced in CI) | Minimal testing, Python 3.8 compatibility |
requirements-slim.txt | 21 packages including markitdown, no nodriver | Docker slim builds, reduced footprint |
requirements.txt | 21 packages, includes setuptools, ddgs | Full development environment |
Sources: requirements.txt1-21 requirements-slim.txt1-21 .github/workflows/unittest.yml24
Install the full development dependencies:
For testing minimal compatibility (Python 3.8):
Sources: README.md170-172 .github/workflows/unittest.yml24 .github/workflows/unittest.yml34-35
The setup.py file defines the package configuration including base dependencies and optional extras groups:
Extras Groups Dependency Map:
Installation Examples:
Key Extras Groups:
| Group | Key Dependencies | Purpose |
|---|---|---|
all | curl_cffi, nodriver, markitdown[all], flask, fastapi, ddgs | Complete feature set with all providers |
slim | curl_cffi, nodriver, pypdf2, python-docx | Common features, reduced footprint (no cairosvg, no markitdown) |
image | pillow, cairosvg, beautifulsoup4 | Image generation and processing |
api | loguru, fastapi, uvicorn, python-multipart, a2wsgi | FastAPI server (Interference API) |
gui | werkzeug, flask, beautifulsoup4, pillow | Flask-based web GUI |
search | beautifulsoup4, pillow, ddgs | Web search via DuckDuckGo |
local | gpt4all | Local model inference with gpt4all |
files | beautifulsoup4, markitdown[all] | Document processing (PDF, DOCX, XLSX) |
webview | pywebview, platformdirs, plyer, cryptography | Desktop webview wrapper (not in slim) |
Sources: setup.py12-96 README.md158-172
Install the package in editable mode for development:
This creates a symbolic link to the source code directory, allowing changes to be immediately reflected without reinstalling. After installation, several command-line entry points become available:
Console Entry Points:
Entry Points Defined in setup.py:
| Command | Module Path | Purpose |
|---|---|---|
g4f | g4f.cli:main | Main CLI interface |
g4f-mcp | g4f.mcp.server:main | MCP server for AI assistants |
g4f-antigravity | g4f.Provider.needs_auth.Antigravity:cli_main | Antigravity provider CLI |
g4f-geminicli | g4f.Provider.needs_auth.GeminiCLI:cli_main | Gemini OAuth CLI |
g4f-qwencode | g4f.Provider.qwen.QwenCode:cli_main | Qwen device code OAuth |
g4f-github-copilot | g4f.Provider.github.GithubCopilot:cli_main | GitHub Copilot CLI |
Sources: setup.py118-127 README.md166-172
The test suite is located in the etc.unittest module. Run tests locally:
The CI workflow tests against two Python versions to ensure compatibility:
CI Test Matrix:
| Python Version | Dependencies | Notes |
|---|---|---|
| 3.8 | requirements-min.txt | Minimum version compatibility |
| 3.12 | requirements.txt (no nodriver) | Latest features, excluding browser automation |
Sources: .github/workflows/unittest.yml1-47 README.md397-398
The project uses three main GitHub Actions workflows:
For detailed CI/CD documentation, see Testing & CI.
Sources: .github/workflows/unittest.yml1-47 .github/workflows/copilot.yml1-58 .github/workflows/build-packages.yml1-490
The application and development tools use environment variables for configuration:
Core Application Environment Variables:
| Variable | Purpose | Used By | Default |
|---|---|---|---|
G4F_PROXY | HTTP proxy for requests | g4f.ChatCompletion | None |
G4F_VERSION | Package version for builds | setup.py | None (required for builds) |
CI/CD Environment Variables:
| Variable | Purpose | Workflow | Example |
|---|---|---|---|
GITHUB_TOKEN | GitHub API authentication | copilot.yml | Auto-provided by GitHub Actions |
GITHUB_REPOSITORY | Repository identifier | copilot.yml | xtekky/gpt4free |
G4F_PROVIDER | Provider for AI review | copilot.yml | Custom provider |
G4F_MODEL | Model for AI review | copilot.yml | g4f.models.gpt_4 |
Environment Variable Usage in Code:
Sources: g4f/__init__.py49-52 setup.py105
The project uses an automated AI code review system implemented in etc/tool/copilot.py:
Copilot Workflow:
Key Functions in etc/tool/copilot.py:
| Function | Purpose | Return Type |
|---|---|---|
get_pr_details(pr_number) | Fetches PR metadata via GitHub API | dict |
get_diff(pr_number) | Retrieves unified diff of PR changes | str |
analyze_code(file_path, diff_text) | Performs line-by-line code analysis | dict |
get_ai_response(prompt) | Calls g4f.ChatCompletion.create() for review | str |
create_analyze_prompt(file_path, diff, pr_title) | Builds prompt for code analysis | str |
create_review_prompt(files_analyzed, pr_details) | Builds prompt for overall review | str |
Environment Configuration:
Sources: .github/workflows/copilot.yml1-58 g4f/__init__.py25-92
The project uses environment variables for version management during builds:
This is set in CI workflows and consumed by setup.py:
The version is also managed in the g4f.version module for runtime checks.
Sources: setup.py105
The repository includes build scripts invoked by CI/CD workflows:
scripts/build-nuitka.sh - Builds standalone executables using Nuitka compiler for WindowsThese scripts are invoked by the build-packages.yml workflow to create cross-platform binaries.
Sources: README.md141-150
After installation, verify the setup works correctly:
Test CLI Installation:
Test Python Import:
Test Basic Functionality:
Flask GUI Server:
FastAPI Server (Interference API):
MCP Server:
Development Server Access Points:
| Service | URL | Purpose |
|---|---|---|
| GUI | http://localhost:8080/chat/ | Web-based chat interface |
| FastAPI Docs | http://localhost:8080/docs | OpenAPI documentation |
| FastAPI (slim docker) | http://localhost:1337/v1 | OpenAI-compatible API |
| noVNC Desktop | http://localhost:7900/?autoconnect=1 | Browser automation access |
| MCP Health | http://localhost:8765/health | MCP server health check |
Sources: README.md182-230 g4f/__init__.py25-92 setup.py118-127
Complete Development Cycle:
Key Development Commands:
| Stage | Command | Purpose |
|---|---|---|
| Setup | git clone https://github.com/xtekky/gpt4free.git | Clone repository |
| Setup | python -m venv venv | Create virtual environment |
| Setup | pip install -r requirements.txt | Install dependencies |
| Setup | pip install -e .[all] | Install package in editable mode |
| Test | python -m etc.unittest | Run test suite |
| Verify | g4f --version | Check CLI installation |
| Verify | python -m g4f.cli gui --port 8080 --debug | Start GUI server |
| Verify | python -m g4f --port 8080 --debug | Start FastAPI server |
| Deploy | git push origin branch | Push changes |
Sources: README.md166-172 README.md182-204 README.md392-399
A complete development setup involves:
pip install -r requirements.txt and pip install -e .[all]python -m etc.unittestThe CI/CD system automatically tests changes against Python 3.8 and 3.12, and performs AI-powered code review on pull requests. For information on contributing provider implementations, see Adding New Providers. For detailed testing and CI documentation, see Testing & CI.
Sources: README.md91-172 setup.py1-183 requirements.txt1-21 .github/workflows/unittest.yml1-47
Refresh this wiki