Repository files navigation

Created by@xtekky,
maintained by@hlohaus

Support the project on GitHub Sponsors ❤️

Live demo & docs:https://g4f.dev | Documentation:https://g4f.dev/docs

GPT4Free (g4f) is a community-driven project that aggregates multiple accessible providers and interfaces to make working with modern LLMs and media-generation models easier and more flexible. GPT4Free aims to offer multi-provider support, local GUI, OpenAI-compatible REST APIs, and convenient Python and JavaScript clients — all under a community-first license.

This README is a consolidated, improved, and complete guide to installing, running, and contributing to GPT4Free.

Table of contents

• What’s included
• Quick links
• Requirements & compatibility
• Installation
  • Docker (recommended)
  • Slim Docker image
  • Windows (.exe)
  • Python (pip / from source / partial installs)
• Running the app
  • GUI (web client)
  • FastAPI / Interference API
  • CLI
  • Optional provider login (desktop in container)
• Using the Python client
  • Synchronous text example
  • Image generation example
  • Async client example
• Using GPT4Free.js (browser JS client)
• Providers & models (overview)
• Local inference & media
• Configuration & customization
• Running on smartphone
• Interference API (OpenAI‑compatible)
• Examples & common patterns
• Contributing
  • How to create a new provider
  • How AI can help you write code
• Security, privacy & takedown policy
• Credits, contributors & attribution
• Powered-by highlights
• Changelog & releases
• Manifesto / Project principles
• License
• Contact & sponsorship
• Appendix: Quick commands & examples

• Python client library and async client.
• Optional local web GUI.
• FastAPI-based OpenAI-compatible API (Interference API).
• Official browser JS client (g4f.dev distribution).
• Docker images (full and slim).
• Multi-provider adapters (LLMs, media providers, local inference backends).
• Tooling for image/audio/video generation and media persistence.

• Website & docs:https://g4f.dev |https://g4f.dev/docs
• PyPI:https://pypi.org/project/g4f
• Docker image:https://hub.docker.com/r/hlohaus789/g4f
• Releases:https://github.com/xtekky/gpt4free/releases
• Issues:https://github.com/xtekky/gpt4free/issues
• Community: Telegram (https://telegram.me/g4f_channel) · Discord News (https://discord.gg/5E39JUWUFa) · Discord Support (https://discord.gg/qXA4Wf4Fsm)

• Python 3.10+ recommended.
• Google Chrome/Chromium for providers using browser automation.
• Docker for containerized deployment.
• Works on x86_64 and arm64 (slim image supports both).
• Some provider adapters may require platform-specific tooling (Chrome/Chromium, etc.). Check provider docs for details.

1. Install Docker:https://docs.docker.com/get-docker/
2. Create persistent directories:
   • Example (Linux/macOS):

     mkdir -p${PWD}/har_and_cookies${PWD}/generated_mediasudo chown -R 1200:1201${PWD}/har_and_cookies${PWD}/generated_media

3. Pull image:

   docker pull hlohaus789/g4f

4. Run container:

   docker run -p 8080:8080 -p 7900:7900 \  --shm-size="2g" \  -v${PWD}/har_and_cookies:/app/har_and_cookies \  -v${PWD}/generated_media:/app/generated_media \  hlohaus789/g4f:latest

Notes:

• Port 8080 serves GUI/API; 7900 can expose a VNC-like desktop for provider logins (optional).
• Increase --shm-size for heavier browser automation tasks.

mkdir -p${PWD}/har_and_cookies${PWD}/generated_mediachown -R 1000:1000${PWD}/har_and_cookies${PWD}/generated_mediadocker run \  -p 1337:8080 -p 8080:8080 \  -v${PWD}/har_and_cookies:/app/har_and_cookies \  -v${PWD}/generated_media:/app/generated_media \  hlohaus789/g4f:latest-slim

Notes:

• The slim image can update the g4f package on startup and installs additional dependencies as needed.
• In this example, the Interference API is mapped to 1337.

👉 Check out the Windows launcher for GPT4Free:
🔗https://github.com/gpt4free/g4f.exe 🚀

1. Download the release artifactg4f.exe.zip from:https://github.com/xtekky/gpt4free/releases/latest
2. Unzip and rung4f.exe.
3. Open GUI at:http://localhost:8080/chat/
4. If Windows Firewall blocks access, allow the application.

Prerequisites:

• Python 3.10+ (https://www.python.org/downloads/)
• Chrome/Chromium for some providers.

Install from PyPI (recommended):

pip install -U g4f[all]

Partial installs

• To install only specific functionality, use optional extras groups. See docs/requirements.md in the project docs.

Install from source:

git clone https://github.com/xtekky/gpt4free.gitcd gpt4freepip install -r requirements.txtpip install -e.

Notes:

• Some features require Chrome/Chromium or other tools; follow provider-specific docs.

• Run via Python:

fromg4f.guiimportrun_guirun_gui()

• Or via CLI:

python -m g4f.cli gui --port 8080 --debug

• Open:http://localhost:8080/chat/

• Start FastAPI server:

python -m g4f --port 8080 --debug

• If using slim docker mapping, Interference API may be available athttp://localhost:1337/v1
• Swagger UI:http://localhost:1337/docs

• Start GUI server:

python -m g4f.cli gui --port 8080 --debug

GPT4Free now includes a Model Context Protocol (MCP) server that allows AI assistants like Claude to access web search, scraping, and image generation capabilities.

Starting the MCP server (stdio mode):

# Using g4f commandg4f mcp# Or using Python modulepython -m g4f.mcp

Starting the MCP server (HTTP mode):

# Start HTTP server on port 8765g4f mcp --http --port 8765# Custom host and portg4f mcp --http --host 127.0.0.1 --port 3000

HTTP mode provides:

• POST http://localhost:8765/mcp - JSON-RPC endpoint
• GET http://localhost:8765/health - Health check

Configuring with Claude Desktop:

Add to yourclaude_desktop_config.json:

{"mcpServers": {"gpt4free": {"command":"python","args": ["-m","g4f.mcp"]    }  }}

Available MCP Tools:

• web_search - Search the web using DuckDuckGo
• web_scrape - Extract text content from web pages
• image_generation - Generate images from text prompts

For detailed MCP documentation, seeg4f/mcp/README.md

• Accessible at:

  http://localhost:7900/?autoconnect=1&resize=scale&password=secret

• Useful for logging into web-based providers to obtain cookies/HAR files.

Install:

pip install -U g4f[all]

Synchronous text example:

fromg4f.clientimportClientclient=Client()response=client.chat.completions.create(model="gpt-4o-mini",messages=[{"role":"user","content":"Hello, how are you?"}],web_search=False)print(response.choices[0].message.content)

Expected:

Hello! How can I assist you today?

Image generation example:

fromg4f.clientimportClientclient=Client()response=client.images.generate(model="flux",prompt="a white siamese cat",response_format="url")print(f"Generated image URL:{response.data[0].url}")

Async client example:

fromg4f.clientimportAsyncClientimportasyncioasyncdefmain():client=AsyncClient()response=awaitclient.chat.completions.create(model="gpt-4o-mini",messages=[{"role":"user","content":"Explain quantum computing briefly"}],    )print(response.choices[0].message.content)asyncio.run(main())

Notes:

• See the full API reference for streaming, tool-calling patterns, and advanced options:https://g4f.dev/docs/client

Use the official JS client in the browser—no backend required.

Example:

<scripttype="module">importClientfrom'https://g4f.dev/dist/js/client.js';constclient=newClient();constresult=awaitclient.chat.completions.create({model:'gpt-4.1',// Or "gpt-4o", "deepseek-v3", etc.messages:[{role:'user',content:'Explain quantum computing'}]});console.log(result.choices[0].message.content);</script>

Notes:

• The JS client is distributed via the g4f.dev CDN for easy usage. Review CORS considerations and usage limits.

• GPT4Free integrates many providers including (but not limited to) OpenAI-compatible endpoints, PerplexityLabs, Gemini, MetaAI, Pollinations (media), and local inference backends.
• Model availability and behavior depend on provider capabilities. See the providers doc for current, supported provider/model lists:https://g4f.dev/docs/providers-and-models

Provider requirements may include:

• API keys or tokens (for authenticated providers)
• Browser cookies / HAR files for providers scraped via browser automation
• Chrome/Chromium or headless browser tooling
• Local model binaries and runtime (for local inference)

• GPT4Free supports local inference backends. Seedocs/local.md for supported runtimes and hardware guidance.
• Media generation (image, audio, video) is supported through providers (e.g., Pollinations). Seedocs/media.md for formats, options, and sample usage.

• Configure via environment variables, CLI flags, or config files. Seedocs/config.md.
• To reduce install size, use partial requirement groups. Seedocs/requirements.md.
• Provider selection: learn how to set defaults and override per-request atdocs/selecting_a_provider.md.
• Persistence: HAR files, cookies, and generated media persist in mapped directories (e.g., har_and_cookies, generated_media).

• The web GUI is responsive and can be accessed from a phone by visiting your host IP:8080 or via a tunnel. Seedocs/guides/phone.md.

• The Interference API enables OpenAI-like workflows routed through GPT4Free provider selection.
• Docs:docs/interference-api.md
• Default endpoint (example slim docker):http://localhost:1337/v1
• Swagger UI:http://localhost:1337/docs

• Streaming completions, stopping criteria, system messages, and tool-calling patterns are documented in:
  • docs/client.md
  • docs/async_client.md
  • docs/requests.md
• Integrations (LangChain, PydanticAI):docs/pydantic_ai.md
• Legacy examples:docs/legacy.md

Contributions are welcome — new providers, features, docs, and fixes are appreciated.

How to contribute:

1. Fork the repository.
2. Create a branch for your change.
3. Run tests and linters.
4. Open a Pull Request with a clear description and tests/examples if applicable.

Repository:https://github.com/xtekky/gpt4free

• Read the guide:docs/guides/create_provider.md
• Typical steps:
  • Implement a provider adapter ing4f/Provider/
  • Add configuration and dependency notes
  • Include tests and usage examples
  • Respect third‑party code licenses and attribute appropriately

• See:docs/guides/help_me.md for prompt templates and workflows to accelerate development.

• Do not store or share sensitive credentials. Use per-provider recommended security practices.
• If your site appears in the project’s links and you want it removed, send proof of ownership totakedown@g4f.ai and it will be removed promptly.
• For production, secure the server with HTTPS, authentication, and firewall rules. Limit access to provider credentials and cookie/HAR storage.

• Core creators:@xtekky (original), maintained by@hlohaus.
• Full contributor graph:https://github.com/xtekky/gpt4free/graphs/contributors
• Notable code inputs and attributions:
  • har_file.py — input fromxqdoo00o/ChatGPT-to-API
  • PerplexityLabs.py — input fromnathanrchn/perplexityai
  • Gemini.py — input fromdsdanielpark/Gemini-API andHanaokaYuzu/Gemini-API
  • MetaAI.py — inspired bymeta-ai-api by Strvm
  • proofofwork.py — input frommissuo/FreeGPT35

Many more contributors are acknowledged in the repository.

• Pollinations AI — generative media:https://github.com/pollinations/pollinations
• MoneyPrinter V2 — example project using GPT4Free:https://github.com/FujiwaraChoki/MoneyPrinterV2
• For a full list of projects and sites using GPT4Free, see:docs/powered-by.md

• Releases and full changelog:https://github.com/xtekky/gpt4free/releases
• Subscribe to Discord/Telegram for announcements.

GPT4Free is guided by community principles:

1. Open access to AI tooling and models.
2. Collaboration across providers and projects.
3. Opposition to monopolistic, closed systems that restrict creativity.
4. Community-centered development and broad access to AI technologies.
5. Promote innovation, creativity, and accessibility.

https://g4f.dev/manifest

This program is licensed under the GNU General Public License v3.0 (GPLv3). See the full license:https://www.gnu.org/licenses/gpl-3.0.txt

Summary:

• You may redistribute and/or modify under the terms of GPLv3.
• The program is provided WITHOUT ANY WARRANTY.

Copyright notice

xtekky/gpt4free: Copyright (C) 2025 xtekkyThis program is free software: you can redistribute it and/or modifyit under the terms of the GNU General Public License as published bythe Free Software Foundation, either version 3 of the License, or(at your option) any later version.This program is distributed in the hope that it will be useful,but WITHOUT ANY WARRANTY; without even the implied warranty ofMERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See theGNU General Public License for more details.

• Maintainers:https://github.com/hlohaus
• Sponsorship:https://github.com/sponsors/hlohaus
• Issues & feature requests:https://github.com/xtekky/gpt4free/issues
• Takedown requests:takedown@g4f.ai

Install (pip):

pip install -U g4f[all]

Run GUI (Python):

python -m g4f.cli gui --port 8080 --debug# orpython -c"from g4f.gui import run_gui; run_gui()"

Docker (full):

docker pull hlohaus789/g4fdocker run -p 8080:8080 -p 7900:7900 \  --shm-size="2g" \  -v${PWD}/har_and_cookies:/app/har_and_cookies \  -v${PWD}/generated_media:/app/generated_media \  hlohaus789/g4f:latest

Docker (slim):

docker run -p 1337:8080 -p 8080:8080 \  -v${PWD}/har_and_cookies:/app/har_and_cookies \  -v${PWD}/generated_media:/app/generated_media \  hlohaus789/g4f:latest-slim

Python usage patterns:

• client.chat.completions.create(...)
• client.images.generate(...)
• Async variants viaAsyncClient

Docs & deeper reading

• Full docs:https://g4f.dev/docs
• Client API docs:https://g4f.dev/docs/client
• Async client docs:https://g4f.dev/docs/async_client
• Provider guides:https://g4f.dev/docs/guides
• Local inference:https://g4f.dev/docs/local

Thank you for using and contributing to GPT4Free — together we make powerful AI tooling accessible, flexible, and community-driven.