How to Configure Proxies for gpt4free Provider Requests: A Complete Guide

To configure proxies for gpt4free provider requests, set the G4F_PROXY environment variable, pass a proxy parameter directly to ChatCompletion.create(), or use the --proxy CLI flag, ensuring aiohttp_socks is installed for SOCKS5 support.

The gpt4free library (hosted at xtekky/gpt4free) routes all provider HTTP requests through a centralized proxy configuration system. Whether you need to bypass regional restrictions, rotate IP addresses, or route traffic through a corporate firewall, understanding how to configure proxies for gpt4free provider requests ensures reliable connectivity across all supported AI providers.

Understanding the Proxy Architecture

The proxy system in gpt4free operates through three distinct layers that cascade from global configuration to per-request overrides:

1. Environment Layer: AppConfig in g4f/config.py loads the G4F_PROXY variable at startup and caches it in AppConfig.proxy.
2. Request Layer: StreamSession in g4f/requests/aiohttp.py receives the proxy string and constructs an aiohttp_socks.ProxyConnector when needed.
3. API Layer: High-level helpers in g4f/__init__.py inject the global proxy into ChatCompletion.create() calls unless explicitly overridden.

Method 1: Configure Proxies Using Environment Variables

The most persistent way to configure proxies for gpt4free provider requests is setting the G4F_PROXY environment variable before importing the library.

In g4f/config.py, the AppConfig class defines the proxy attribute and loads it from the environment:

# g4f/config.py

class AppConfig:
    proxy: str = None
    
    @classmethod
    def load_from_env(cls):
        cls.proxy = os.environ.get("G4F_PROXY", cls.proxy)

Set the variable and run your script:

export G4F_PROXY="http://user:pass@127.0.0.1:3128"
python my_script.py

Once set, all provider requests automatically route through this proxy without additional code changes.

Method 2: Pass Proxies Directly to API Calls

For per-request control, pass the proxy parameter directly to ChatCompletion.create() or any provider method. This overrides the global G4F_PROXY setting for that specific call.

In g4f/__init__.py, the _prepare_request function checks for explicit proxy arguments and falls back to the environment variable only when omitted:

# g4f/__init__.py

def _prepare_request(...):
    if proxy is None:
        proxy = os.getenv("G4F_PROXY")
    ...

Override the proxy for a single request:

import g4f

response = g4f.ChatCompletion.create(
    model='gpt-4',
    messages=[{'role': 'user', 'content': 'Hello!'}],
    proxy='http://10.0.0.1:8080'  # Per-request proxy

)
print(response)

Method 3: Configure Proxies via CLI

When using the g4f-cli command-line interface, append the --proxy flag to route all provider requests through your specified proxy server.

The CLI argument is defined in g4f/cli/__init__.py:

# g4f/cli/__init__.py

parser.add_argument("--proxy", help="Proxy configuration for requests")

Usage example:

g4f-cli chat \
    --model gpt-4 \
    --provider OpenaiChat \
    --proxy http://proxy.example.com:8080 \
    "Explain quantum computing"

The CLI flag takes precedence over the G4F_PROXY environment variable but applies to all requests within that single CLI invocation.

SOCKS5 Proxy Support and Requirements

For SOCKS5 proxies (including Tor), gpt4free requires the aiohttp_socks package. The library detects proxy schemes and automatically constructs the appropriate connector.

In g4f/requests/aiohttp.py, the get_connector function handles proxy connector creation:

# g4f/requests/aiohttp.py

def get_connector(proxy: str = None, ...):
    if proxy is not None:
        try:
            from aiohttp_socks import ProxyConnector
            return ProxyConnector.from_url(proxy)
        except ImportError:
            raise MissingRequirementsError('Install "aiohttp_socks" package for proxy support')

Install the dependency:

pip install aiohttp_socks

Then use SOCKS5 URLs:

import g4f

response = g4f.ChatCompletion.create(
    model='gpt-4',
    messages=[{'role': 'user', 'content': 'Hello'}],
    proxy='socks5://127.0.0.1:1080'
)

Key Implementation Files

Understanding these source files helps debug proxy issues and extend functionality:

File	Role in Proxy Configuration
g4f/config.py	Defines AppConfig.proxy and loads G4F_PROXY from environment variables at startup.
g4f/__init__.py	Contains _prepare_request which injects the global proxy into API calls when not explicitly provided.
g4f/cli/__init__.py	Implements the --proxy CLI argument that overrides environment settings for command-line usage.
g4f/requests/aiohttp.py	Houses StreamSession and get_connector which construct aiohttp sessions with ProxyConnector for SOCKS/HTTP proxies.

Summary

• Environment Variable: Set G4F_PROXY before importing gpt4free to apply a global proxy to all provider requests.
• Per-Request Override: Pass proxy="http://..." directly to ChatCompletion.create() or provider methods to override the global setting.
• CLI Flag: Use g4f-cli --proxy <url> to route command-line requests through a specific proxy.
• SOCKS5 Support: Install aiohttp_socks to enable socks5:// proxy schemes; the library raises MissingRequirementsError if the package is absent.
• Source Architecture: Proxy handling flows through AppConfig → _prepare_request → StreamSession → get_connector in the respective source files.

Frequently Asked Questions

How do I set a global proxy for all gpt4free requests?

Export the G4F_PROXY environment variable before running your Python script. The AppConfig class in g4f/config.py reads this variable at import time and caches it for all subsequent provider requests. This approach requires no code changes to existing API calls.

Can I use SOCKS5 proxies with gpt4free?

Yes, but you must install the optional aiohttp_socks package using pip install aiohttp_socks. Once installed, pass a SOCKS5 URL like socks5://127.0.0.1:1080 to the proxy parameter or G4F_PROXY environment variable. The get_connector function in g4f/requests/aiohttp.py automatically constructs a ProxyConnector for these URLs.

Why do I get a MissingRequirementsError when using proxies?

This error occurs when you attempt to use any proxy (HTTP or SOCKS) without having the aiohttp_socks package installed, or when the provider requires specific connector features. Install the package with pip install aiohttp_socks to resolve the error and enable full proxy support across all providers.

Does the CLI --proxy flag override the G4F_PROXY environment variable?

Yes, the --proxy flag provided to g4f-cli takes precedence over the G4F_PROXY environment variable for that specific CLI invocation. The CLI parser in g4f/cli/__init__.py passes this value directly to the request kwargs, which overrides the global config during the execution of that command.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}