gpt4free

GPT4Free (g4f)

---

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
  • Sandbox desktop (Docker)
  • Windows (.exe)
  • Python (pip / from source / partial installs)
• Running the app
  • GUI (web client)
  • FastAPI / Inference 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
• Inference 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

• Python client library and async client.
• Optional local web GUI.
• FastAPI-based OpenAI-compatible API (Inference 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.

---

Quick links

• 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)

---

Related projects

• g4f-go – Self-contained Go launcher for g4f (downloads CPython + g4f on demand; includes the g4f-go sandbox launcher for Docker, Podman and udocker)
• remote_desktop – WebRTC-based remote desktop host/viewer
• sandbox-desktop – TigerVNC + Xfce + noVNC desktop in Docker with preinstalled coding agents (menu/tool list, start script, Dockerfile)

---

Requirements & compatibility

• 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.

---

Installation

Docker (recommended)

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

     mkdir -p ${PWD}/har_and_cookies ${PWD}/generated_media
     sudo 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.

Slim Docker image (x64 & arm64)

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

Notes:

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

Sandbox desktop (Docker)

A full Xfce desktop (TigerVNC + noVNC) with the g4f API and a one-click one-click menu for 100+ AI tools and providers — coding agents, browsers, gateways, local runtimes and assistants. See docs/sandbox-desktop for the start script, clipboard, scaling, app volume, user id, password and domain-routing options, and docker/sandbox-menu/README.md for the menu, the tool list and the settings.

docker run -d --name g4f-sandbox-desktop \
  --cap-add NET_ADMIN \
  -p 127.0.0.1:8080:8080 -p 127.0.0.1:5900:5900 \
  --shm-size="2gb" \
  -v ${PWD}:/app/gpt4free \
  -v ${PWD}/sandbox-home/.config:/home/pn/.config \
  -v ${PWD}/sandbox-home/.local:/home/pn/.local \
  hlohaus789/g4f:latest-sandbox-desktop

• Desktop (browser): http://127.0.0.1:8080/desktop/ · API: http://127.0.0.1:8080/ · Direct VNC: 127.0.0.1:5900
• The ports bind to 127.0.0.1 by default (localhost only, not every host interface). Set SANDBOX_BIND_ADDR=0.0.0.0 to expose the desktop on the LAN; bin/start-sandbox-desktop.sh --bind <addr> does the same.
• The image starts an egress firewall (needs --cap-add NET_ADMIN): the sandbox can reach the public internet, but connections to private, link-local and reserved networks — the host LAN, other Docker networks and cloud metadata — are rejected. Loopback inside the container stays usable, so the g4f API, its *.g4f.local router and local gateways keep working. Replies to connections that come in from the host are allowed, so the published desktop/API ports stay reachable even though the host address is in a blocked range; the filter only stops the sandbox from starting such connections itself. Outbound file-sharing/sync protocols (SMB, NetBIOS, NFS, AFP, FTP/TFTP, rsync, iSCSI, rpcbind) and common crypto-mining pool ports are rejected too. Host-side services reached through host.docker.internal, 172.17.0.1 or the host's LAN address are blocked as well; run them inside the sandbox or set SANDBOX_BLOCK_LOCAL_NETWORK=0 to disable the filter for a trusted setup. If the filter cannot be installed the sandbox still starts with a warning; set SANDBOX_FIREWALL_STRICT=1 to make that fatal.
• -v ${PWD}:/app/gpt4free mounts your app into the sandbox at the path the image's editable g4f install points at, so the API serves your code and the agents can edit it. Mount at /app/gpt4free, not /app.
• -v ${PWD}/sandbox-home/.config:/home/pn/.config and …/.local:/home/pn/.local keep agent configs, credentials, caches and the sandbox settings across container restarts — without them every new container starts with an empty home and every tool asks for its login again. Do not mount over /home/pn itself: the embedded Python and g4f runtime live in /home/pn/.g4f.
• To give the agents a throwaway profile instead, point HOME at a mounted directory: -v ${PWD}/agent-home:/home/pn/work plus Sandbox Settings → sandbox-cli settings --home /home/pn/work.
• bin/start-sandbox-desktop.sh wraps the same run (and docker/docker-compose.sandbox-desktop.yml) with --build, --pull, --port, --bind, --app-dir, --user-id, --api-key, --domain-suffix, --no-domain-router, shell, logs and stop. --api-key KEY protects the desktop/API with a password (any username works in the browser login); see docs/sandbox-desktop.
• The sandbox user (pn) runs with uid/gid 1000 by default. On a host whose user has another id, build the image with --build-arg G4F_USER_ID="$(id -u)" (or run bin/start-sandbox-desktop.sh --user-id "$(id -u)"; it rebuilds when the existing image was built for a different id). Matching the id keeps the bind-mounted sandbox-home and files written under /app/gpt4free owned by your host user.

Sandbox launcher (g4f-go sandbox)

Download g4f-go from the release assets for Windows, Linux, macOS or Termux (amd64/arm64). The sandbox subcommand requires only Docker, Podman or, on Termux/Android, udocker; it does not embed the image and pulls it on demand:

g4f-go sandbox                    # small API-only sandbox (latest-slim)
g4f-go sandbox --desktop          # full desktop image, pulled on first use
g4f-go sandbox --desktop install chrome
g4f-go sandbox-cli list           # shorthand for `g4f-go sandbox --desktop cli`
g4f-go sandbox status
g4f-go sandbox down

The default API-only mode uses the multi-arch latest-slim image; --desktop pulls latest-sandbox-desktop only when the desktop is requested. Tools are installed on demand from the sandbox menu or with g4f-go sandbox --desktop install <tool>. On Termux/Android the same command uses udocker (installed with pip on first use) to run those images without root; the native API-only backend is still available with --backend termux. See g4f-go and the sandbox desktop documentation.

Python Installation (pip / from source / partial installs)

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

GUI (web client)

• Run via Python:

from g4f.gui import run_gui
run_gui()

• Or via CLI:

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

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

FastAPI / Inference API

• Start FastAPI server:

python -m g4f --port 8080 --debug

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

CLI

• Start GUI server:

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

MCP Server

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 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
• polli_publish_app - Publish a built app from the workspace to https://<name>.pollinations.app with the Pollinations CLI

For detailed MCP documentation, see g4f/mcp/README.md

Optional provider login (desktop within container)

• Accessible at:

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

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

---

Using the Python client

Install:

pip install -U g4f[all]

Synchronous text example:

from g4f.client import Client

client = Client()
response = client.chat.completions.create(
    model="auto",
    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:

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="auto",
        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)

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

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: 'auto',  // Or "glm-5.3", "kimi-k3", 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)

• 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)

---

Local inference & media

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

---

Configuration & customization

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

---

Running on smartphone

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

---

Inference API (OpenAI‑compatible)

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

---

Examples & common patterns

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

---

Contributing

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

How to create a new provider

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

How AI can help you write code

• See: docs/guides/help_me for prompt templates and workflows to accelerate development.
• Automatic development loop: docs/dev-pipeline explains bin/dev-pipeline, which reads tasks from AGENTS.md and implements them with working free models from pi-freeflow.

---

Security, privacy & takedown policy

• Do not store or share sensitive credentials. Use per-provider recommended security practices.
• Conversations are stored locally on your device by default; server/cloud synchronization (Secret Storage) is strictly opt-in and client-side encrypted.
• If your site appears in the project’s links and you want it removed, send proof of ownership to https://g4f.dev/community 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.

---

Credits, contributors & attribution

• Core creators: @xtekky (original), maintained by @hlohaus.
• Full contributor graph: https://github.com/xtekky/gpt4free/graphs/contributors

Many more contributors are acknowledged in the repository.

---

Powered-by highlights

• 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

---

Changelog & releases

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

---

Manifesto / Project principles

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/manifesto

---

License

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

• Maintainers: https://github.com/hlohaus
• Community & contact: https://g4f.dev/community
• Sponsorship: https://github.com/sponsors/hlohaus
• Issues & feature requests: https://github.com/xtekky/gpt4free/issues

---

Appendix: Quick commands & examples

Install g4f-go (launcher):

curl -fsSL https://raw.githubusercontent.com/xtekky/gpt4free/main/bin/install.sh | bash

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.