Configuration

July 24, 2026 · View on GitHub

ariadne-codegen reads configuration from [tool.ariadne-codegen] section in your pyproject.toml. You can use other configuration file with --config option, eg. ariadne-codegen --config custom_file.toml

Minimal configuration for client generation:

[tool.ariadne-codegen]
schema_path = "schema.graphql"
queries_path = "queries.graphql"

Required settings:

  • queries_path - path to file/directory with queries (Can be optional if enable_custom_operations is used)

Exactly one of the following parameters is required - they are mutually exclusive, so only one schema source may be used at a time (see Schema sources):

  • schema_path - path to file/directory with graphql schema
  • schema_paths - list of local paths and/or installed-package sources to build the schema from
  • remote_schema_url - url to graphql server, where introspection query can be performed

Optional settings:

  • remote_schema_headers - extra headers that are passed along with introspection query, eg. {"Authorization" = "Bearer token"}. To include an environment variable in a header value, prefix the variable with $, eg. {"Authorization" = "$AUTH_TOKEN"}
  • remote_schema_verify_ssl (defaults to true) - a flag that specifies whether to verify ssl while introspecting remote schema
  • remote_schema_timeout (defaults to 5) - timeout in seconds while introspecting remote schema
  • remote_schema_http_client_path - absolute import path to the HTTP client used to introspect remote schema. If not provided, default httpx client is used. See Remove schema client customization below for details.
  • target_package_name (defaults to "graphql_client") - name of generated package
  • target_package_path (defaults to cwd) - path where to generate package
  • client_name (defaults to "Client") - name of generated client class
  • client_file_name (defaults to "client") - name of file with generated client class
  • base_client_name (defaults to "AsyncBaseClient") - name of base client class. See Base Client customization below for details.
  • base_client_file_path (defaults to .../ariadne_codegen/client_generators/dependencies/async_base_client.py) - path to file where base_client_name is defined
  • base_client_module_name (defaults to the file name of base_client_file_path) - name of the module the base client is copied to and imported from in the generated package
  • enums_module_name (defaults to "enums") - name of file with generated enums models
  • input_types_module_name (defaults to "input_types") - name of file with generated input types models
  • fragments_module_name (defaults to "fragments") - name of file with generated fragments models
  • include_comments (defaults to "stable") - option which sets content of comments included at the top of every generated file. Valid choices are: "none" (no comments), "timestamp" (comment with generation timestamp), "stable" (comment contains a message that this is a generated file)
  • convert_to_snake_case (defaults to true) - a flag that specifies whether to convert fields and arguments names to snake case
  • include_all_inputs (defaults to true) - a flag specifying whether to include all inputs defined in the schema, or only those used in supplied operations
  • include_all_enums (defaults to true) - a flag specifying whether to include all enums defined in the schema, or only those used in supplied operations
  • async_client (defaults to true) - default generated client is async, change this to option false to generate synchronous client instead
  • opentelemetry_client (defaults to false) - default base clients don't support any performance tracing. Change this option to true to use the base client with Open Telemetry support.
  • multipart_uploads (defaults to true) - when set to false, a lighter base client variant is generated that omits multipart file upload support.
  • files_to_include (defaults to []) - list of files which will be copied into generated package
  • plugins (defaults to []) - list of plugins to use during generation
  • enable_custom_operations (defaults to false) - enables building custom operations. Generates additional files that contains all the classes and methods for generation. Adds graphql-core to the generated package's runtime dependencies.
  • defer_model_build (defaults to false) - defers building of generated Pydantic models until they are first used. Sets defer_build=True on the generated BaseModel and skips the eager model_rebuild() calls, so importing the generated package is much faster for large schemas. See Improving import performance.
  • use_alias_generator (defaults to false) - sets alias_generator=to_camel on the generated BaseModel, so fields no longer need their own Field(alias=...) when the alias can be derived from the Python name. Requires pydantic >= 2.8. See Improving import performance.
  • lazy_imports (defaults to false) - generates an __init__.py that imports each module the first time a name from it is used, instead of importing all of them up front, so an application only pays for the models it touches. Also enables the ClientForwardRefsPlugin, which is needed for the deferral to hold: it keeps client.py from importing the input types it only names in annotations. See Improving import performance.
  • include_typename (defaults to true) - a flag that specifies whether to include the __typename field in generated models
  • ignore_extra_fields (defaults to true) - when true, generated models ignore extra fields returned by the server; set to false to add extra="forbid" to the base model so unexpected fields raise a validation error
  • default_optional_fields_to_none (defaults to false) - when true, optional fields in generated models default to None instead of being required keyword arguments
  • skip_validation_rules (defaults to ["NoUnusedFragments"]) - list of graphql-core validation rule names to skip when validating operations against the schema

Scalars

Custom scalar mappings are configured in per-scalar subsections rather than a single key:

[tool.ariadne-codegen.scalars.{graphql scalar name}]
type = "..."

See Custom scalars for the full syntax.

Introspection query settings:

These options control which fields are included in the GraphQL introspection query when using remote_schema_url. See Schema sources for more details.

  • introspection_descriptions (defaults to false) – include descriptions in the introspection result
  • introspection_input_value_deprecation (defaults to false) – include deprecation information for input values
  • introspection_specified_by_url (defaults to false) – include specifiedByUrl for custom scalars
  • introspection_schema_description (defaults to false) – include schema description
  • introspection_directive_is_repeatable (defaults to false) – include isRepeatable information for directives
  • introspection_input_object_one_of (defaults to false) – include oneOf information for input objects

Remote schema client customization

By default, httpx is used to introspect a remote schema. Another client can be used instead by setting remote_schema_http_client_path. The provided client must implement the following protocol:

class Response(Protocol):
    status_code: int

    def json(self, **kwargs: Any) -> Any: ...


class HttpClient(Protocol):
    def post(
        self,
        url: Any | str,
        json: Any | None = None,
        headers: Any | None = None,
        verify: Any | None = None,
        timeout: Any | None = None,
        **kwargs: Any,
    ) -> Response: ...

If the provided import path points to a module, the module itself must implement the protocol. If the provided import path points to a callable, it is called with a single argument: config_dict: dict (the parsed pyproject.toml), and the returned object is expected to implement HttpClient protocol.

Base Client customization

The base_client_file_path and base_client_name can be used to provide a custom base client implementation. It should implement the following protocol for async client:

class AsyncBaseClient(Protocol):
    async def execute(
        self,
        query: str,
        operation_name: Optional[str] = None,
        variables: Optional[dict[str, Any]] = None,
        **kwargs: Any,
    ) -> Response: ...

    def get_data(self, response: Response) -> dict[str, Any]: ...

Protocol for sync client:

class BaseClient(Protocol):
    def execute(
        self,
        query: str,
        operation_name: Optional[str] = None,
        variables: Optional[dict[str, Any]] = None,
        **kwargs: Any,
    ) -> Response: ...

    def get_data(self, response: Response) -> dict[str, Any]: ...

Several settings have dedicated guides that explain them in context: