This document provides a comprehensive reference for configuring g4f through environment variables, configuration files, and deployment settings. Environment configuration controls system behavior, provider integration, Docker deployment parameters, and runtime settings.
For API-specific configuration including authentication and security, see Authentication & Security. For provider-specific API keys and credentials, see Provider-Specific Auth Patterns.
The g4f configuration system supports multiple configuration sources with the following priority order (highest to lowest):
.env files loaded via python-dotenvConfiguration Loading Flow
Sources: g4f/__init__.py49-52 setup.py39 requirements.txt19
| Variable | Type | Description | Default | Used In |
|---|---|---|---|---|
G4F_VERSION | string | Package version string | Set during build | Docker images, setup.py |
G4F_DIR | path | Application working directory | /app | Docker containers |
G4F_LIVE | boolean | Enable live Git updates | false | Slim Docker image |
G4F_USER | string | Container user name | g4f | Docker (slim/armv7) |
G4F_USER_ID | integer | Container user ID | 1000 | Docker (slim/armv7) |
Version Management
The G4F_VERSION variable is set during the build process and embedded into the package. In Docker builds, it controls which version is installed:
Sources: docker/Dockerfile3-4 docker/Dockerfile-slim3-4 setup.py105
| Variable | Type | Description | Example | Used By |
|---|---|---|---|---|
G4F_PROXY | URL | HTTP/HTTPS/SOCKS proxy for provider requests | http://proxy.example.com:8080 | ChatCompletion, Client |
OLLAMA_HOST | URL | Local OLLAMA server endpoint | host.docker.internal:11434 | Ollama provider |
Proxy Configuration Flow
The proxy configuration is checked during request preparation and applied to all provider requests:
The proxy is applied in g4f/__init__.py49-52:
Sources: g4f/__init__.py49-52 docker-compose.yml14-15
| Variable | Type | Description | Default | Docker Image |
|---|---|---|---|---|
SE_SCREEN_WIDTH | integer | Selenium screen width (for browser automation) | 1850 | Full (selenium-based) |
G4F_LOGIN_URL | URL | Browser desktop access URL (noVNC) | http://localhost:7900/?autoconnect=1&resize=scale&password=secret | Full |
HOME | path | User home directory | /home/{G4F_USER} | Slim, ARMv7 |
PATH | path | Executable search path | Includes .local/bin, .cargo/bin | All images |
Docker Environment Configuration
Sources: docker/Dockerfile3-8 docker/Dockerfile-slim3-12 docker/Dockerfile-armv73-27
Provider-specific environment variables are used for authentication and API access. These are typically read directly by provider implementations.
| Variable Pattern | Example | Provider Usage |
|---|---|---|
{PROVIDER}_API_KEY | OPENAI_API_KEY | OpenAI-compatible providers |
{PROVIDER}_TOKEN | GEMINI_TOKEN | Token-based authentication |
{PROVIDER}_BASE_URL | AZURE_BASE_URL | Custom endpoint URLs |
In docker-compose.yml, the OLLAMA host is configured to allow the container to access the host machine:
This enables g4f running in Docker to connect to OLLAMA running on the host system.
Sources: docker-compose.yml14-15
The g4f system supports .env files through the python-dotenv library. Environment variables defined in .env files are automatically loaded into the environment.
Supported .env File Locations
.env File Format
Sources: setup.py39 requirements.txt19
Docker Compose provides declarative environment configuration through the environment section:
docker-compose.yml Structure
Configuration Merging in Docker Compose
Sources: docker-compose.yml1-16 docker-compose-slim.yml1-13
Environment variables set in Dockerfiles with ENV directives become part of the image and serve as defaults:
Full Docker Image Environment
Slim Docker Image Environment
ARMv7 Image PATH Configuration
The ARMv7 image includes Rust's cargo bin directory in the PATH for building native extensions.
Runtime environment variables (set via -e, --env-file, or docker-compose.yml) override build-time defaults:
Sources: docker/Dockerfile6-8 docker/Dockerfile-slim8-30 docker/Dockerfile-armv78-27
The slim Docker image supports live Git updates controlled by the G4F_LIVE environment variable.
Update Script Implementation
The update script docker/update.sh1-24 runs in a continuous loop:
Update Tool Logic
The etc/tool/update.py5-8 checks the environment variable before executing:
Sources: docker/Dockerfile-slim4-35 etc/tool/update.py1-19 docker/update.sh1-24
Docker deployments require volume mounts for persistent data storage.
| Host Path | Container Path | Purpose | Permissions |
|---|---|---|---|
./har_and_cookies | /app/har_and_cookies | HAR files, cookies, session data | 1200:1201 (full) or 1000:1000 (slim) |
./generated_media | /app/generated_media | Generated images, audio, video | 1200:1201 (full) or 1000:1000 (slim) |
Volume Mount Architecture
Setting Up Persistent Directories
Sources: README.md107-129 docker-compose.yml8-10 docker-compose-slim.yml9-10
Different deployment modes expose different ports for various services.
| Port | Service | Description | Image |
|---|---|---|---|
| 8080 | GUI + API | Web GUI and backend API | All |
| 1337 | FastAPI | OpenAI-compatible Interference API | Optional mapping |
| 7900 | noVNC | Browser desktop for provider login | Full only |
Port Exposure Architecture
Docker Compose Port Configuration
Full image (with browser automation):
Slim image (minimal):
Sources: docker-compose.yml10-13 docker-compose-slim.yml11-13 README.md116-136
The full Docker image uses supervisor to manage multiple processes including the API server and Selenium components.
API Server Process
The docker/supervisor-api.conf1-12 defines the g4f API server:
Selenium Components
The docker/supervisor.conf1-50 manages Xvfb, VNC, and noVNC:
Sources: docker/supervisor.conf1-50 docker/supervisor-api.conf1-12
Sources: docker-compose.yml1-16 docker-compose-slim.yml1-13
Inside Docker Container:
In Python Code:
| Issue | Symptom | Solution |
|---|---|---|
| Volume permissions | Permission denied errors when reading HAR files | Run chown -R 1200:1201 (full) or 1000:1000 (slim) |
| Proxy not working | Requests fail or bypass proxy | Ensure G4F_PROXY is set before container start |
| OLLAMA connection | Local models not accessible | Use host.docker.internal on Docker Desktop |
| Live updates disabled | Container doesn't pull latest code | Set G4F_LIVE=true in slim image |
Sources: README.md107-109 g4f/__init__.py49-52 etc/tool/update.py5-8
Refresh this wiki