Repository: xtekky/gpt4free

Stars: 66025

README.md Copy Chapter

GPT4Free (g4f)

   

<p align="center">
<img src="https://g4f.dev/docs/images/477107515-7f60c240-00fa-4c37-bf7f-ae5cc20906a1.png" alt="GPT4Free logo" height="200" />
</p>

<p align="center">
<span style="background: linear-gradient(45deg, #12c2e9, #c471ed, #f64f59); -webkit-background-clip: text; -webkit-text-fill-color: transparent;">
<strong>Created by <a href="https://github.com/xtekky">@xtekky</a>,<br> maintained by <a href="https://github.com/hlohaus">@hlohaus</a></strong>
</span>
</p>
<p align="center">
<span>Support the project on</span>
<a href="https://github.com/sponsors/hlohaus" target="_blank" rel="noopener noreferrer">
GitHub Sponsors
</a>
❤️
</p>
<p align="center">
Live demo & docs: https://g4f.dev | Documentation: https://g4f.dev/docs
</p>

---

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

---

What’s included Copy Chapter

---

Quick links Copy Chapter

---

Requirements & compatibility Copy Chapter

---

Installation Copy Chapter

Docker (recommended) Copy Section

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

docker pull hlohaus789/g4f

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

Slim Docker image (x64 & arm64) Copy Section

mkdir -p ${PWD}/har_and_cookies ${PWD}/generated_media
chown -R 1000:1000 ${PWD}/har_and_cookies ${PWD}/generated_media
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

Windows Guide (.exe) Copy Section

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

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

Python Installation (pip / from source / partial installs) Copy Section

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.git
cd gpt4free
pip install -r requirements.txt
pip install -e .

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

---

Running the app Copy Chapter

GUI (web client) Copy Section

from g4f.gui import run_gui
run_gui()

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

FastAPI / Interference API Copy Section

python -m g4f --port 8080 --debug

CLI Copy Section

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

MCP Server Copy Section

Starting the MCP server (stdio mode):

Using g4f command

g4f mcp
Or using Python module

python -m g4f.mcp

Starting the MCP server (HTTP mode):

Start HTTP server on port 8765

g4f mcp --http --port 8765
Custom host and port

g4f 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 your claude_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, see g4f/mcp/README.md

Optional provider login (desktop within container) Copy Section

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

---

Using the Python client Copy Chapter

Install:

pip install -U g4f[all]

Synchronous text example:

from g4f.client import Client
client = 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)

Hello! How can I assist you today?

Image generation example:

from g4f.client import Client
client = 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:

from g4f.client import AsyncClient
import asyncio
async def main():
    client = AsyncClient()
    response = await client.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

---

Using GPT4Free.js (browser JS client) Copy Chapter

Example:

<script type="module">
  import Client from 'https://g4f.dev/dist/js/client.js';
  const client = new Client();
  const result = await client.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.

---

Providers & models (overview) Copy Chapter

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)

---

Local inference & media Copy Chapter

---

Configuration & customization Copy Chapter

---

Running on smartphone Copy Chapter

---

Interference API (OpenAI‑compatible) Copy Chapter

---

Examples & common patterns Copy Chapter

---

Contributing Copy Chapter

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

How to create a new provider Copy Section

How AI can help you write code Copy Section

---

Security, privacy & takedown policy Copy Chapter

---

Credits, contributors & attribution Copy Chapter

Many more contributors are acknowledged in the repository.

---

Powered-by highlights Copy Chapter

---

Changelog & releases Copy Chapter

---

Manifesto / Project principles Copy Chapter

https://g4f.dev/manifesto

---

License Copy Chapter

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 xtekky
This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the 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 of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

---

Contact & sponsorship Copy Chapter

---

Appendix: Quick commands & examples Copy Chapter

Install (pip):

pip install -U g4f[all]

Run GUI (Python):

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

python -c "from g4f.gui import run_gui; run_gui()"

Docker (full):

docker pull hlohaus789/g4f
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

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 via AsyncClient

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/providers
- 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.