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

> Learn how to configure proxies for gpt4free provider requests using environment variables, the create() method, or the CLI. Master proxy settings for enhanced access.

- Repository: [Tekky/gpt4free](https://github.com/xtekky/gpt4free)
- Tags: how-to-guide
- Published: 2026-03-04

---

**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`](https://github.com/xtekky/gpt4free/blob/main/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`](https://github.com/xtekky/gpt4free/blob/main/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`](https://github.com/xtekky/gpt4free/blob/main/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`](https://github.com/xtekky/gpt4free/blob/main/g4f/config.py), the `AppConfig` class defines the proxy attribute and loads it from the environment:

```python

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

```bash
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`](https://github.com/xtekky/gpt4free/blob/main/g4f/__init__.py), the `_prepare_request` function checks for explicit proxy arguments and falls back to the environment variable only when omitted:

```python

# g4f/__init__.py

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

```

Override the proxy for a single request:

```python
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`](https://github.com/xtekky/gpt4free/blob/main/g4f/cli/__init__.py):

```python

# g4f/cli/__init__.py

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

```

Usage example:

```bash
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`](https://github.com/xtekky/gpt4free/blob/main/g4f/requests/aiohttp.py), the `get_connector` function handles proxy connector creation:

```python

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

```bash
pip install aiohttp_socks

```

Then use SOCKS5 URLs:

```python
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`](https://github.com/xtekky/gpt4free/blob/main/g4f/config.py) | Defines `AppConfig.proxy` and loads `G4F_PROXY` from environment variables at startup. |
| [`g4f/__init__.py`](https://github.com/xtekky/gpt4free/blob/main/g4f/__init__.py) | Contains `_prepare_request` which injects the global proxy into API calls when not explicitly provided. |
| [`g4f/cli/__init__.py`](https://github.com/xtekky/gpt4free/blob/main/g4f/cli/__init__.py) | Implements the `--proxy` CLI argument that overrides environment settings for command-line usage. |
| [`g4f/requests/aiohttp.py`](https://github.com/xtekky/gpt4free/blob/main/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`](https://github.com/xtekky/gpt4free/blob/main/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`](https://github.com/xtekky/gpt4free/blob/main/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`](https://github.com/xtekky/gpt4free/blob/main/g4f/cli/__init__.py) passes this value directly to the request kwargs, which overrides the global config during the execution of that command.