Command-line options

Command-line options

Agda accepts the following options.

General options

--help[={TOPIC}], -?[{TOPIC}]

Show basically this help, or more help about TOPIC. Current topics available: warning.


For use with the Emacs mode (no need to invoke yourself).


New in version 2.6.1.

For use with other editors such as Atom (no need to invoke yourself).

--interactive, -I

Start in interactive mode (no longer supported).


New in version 2.6.1.

Turn off the analysis whether a type signature likens that of a projection.

Projection-likeness is an optimization that reduces the size of terms by dropping parameter-like reconstructible function arguments. Thus, it is advisable to leave this optimization on, the flag is meant for debugging Agda.


Only scope-check the top-level module, do not type-check it (see Quicker generation without typechecking).

--version, -V

Show version number.


New in version 2.6.2.

Outputs the root (AGDA_DIR) of the directory structure holding Agda’s data files such as core libraries, style files for the backends etc.


See Compilers for backend-specific options.


Set DIR as directory for compiler output (default: the project root).


Do not treat the requested module as the main module of a program when compiling.


Set PATH as the executable to call to compile the backend’s output (default: ghc for the GHC backend).

Generating highlighted source code


Count extended grapheme clusters when generating LaTeX code (see Counting Extended Grapheme Clusters).


Set URL of the CSS file used by the HTML files to URL (can be relative).


Generate a Dot file FILE with a module dependency graph.


Generate HTML files with highlighted source code (see Generating HTML).


Set directory in which HTML files are placed to DIR (default: html).


Whether to highlight non-Agda code as comments in generated HTML files (default: all; see Generating HTML).


Generate LaTeX with highlighted source code (see Generating LaTeX).


Set directory in which LaTeX files are placed to DIR (default: latex).


Generate Vim highlighting files.

Imports and libraries

(see Library Management)


Ignore all interface files, including builtin and primitive modules; only use this if you know what you are doing!


Ignore interface files (re-type check everything, except for builtin and primitive modules).

--include-path={DIR}, -i={DIR}

Look for imports in DIR.

--library={DIR}, -l={LIB}

Use library LIB.


Use {FILE} instead of the standard libraries file.


New in version 2.6.1.

Read and write interface files next to the Agda files they correspond to (i.e. do not attempt to regroup them in a _build/ directory at the project’s root).


Don’t use default library files.


Don’t use any library files.

Command-line and pragma options

The following options can also be given in .agda files using the OPTIONS pragma.


--caching, --no-caching

Enable [disable] caching of typechecking (default).

Default: --caching

Printing and debugging


Don’t use unicode characters to print terms.


Show implicit arguments when printing.


Show irrelevant arguments when printing.

--verbose={N}, -v={N}

Set verbosity level to N.

Copatterns and projections

--copatterns, --no-copatterns

Enable [disable] definitions by copattern matching (see Copatterns).

Default: --copatterns


Make postfix projection notation the default.

Experimental features

--confluence-check, --local-confluence-check

New in version 2.6.1.

Enable optional (global or local) confluence checking of REWRITE rules (see Confluence checking).


Enable cubical features. Turns on --without-K (see Cubical).


Enable potentially unsound irrelevance features (irrelevant levels, irrelevant data matching) (see Irrelevance).


Enable injective type constructors (makes Agda anti-classical and possibly inconsistent).


Enable declaration and use of REWRITE rules (see Rewriting).


Enable system calls during type checking (see Reflection).

Errors and warnings


New in version 2.6.1.

Succeed and create interface file regardless of incomplete pattern-matching definitions. See, also, the NON_COVERING pragma.


Succeed and create interface file regardless of unsolved meta variables (see Metavariables).


Do not warn about not strictly positive data types (see Positivity Checking).


Do not warn about possibly nonterminating code (see Termination Checking).

--warning={GROUP|FLAG}, -W {GROUP|FLAG}

Set warning group or flag (see Warnings).

Pattern matching and equality

--exact-split, --no-exact-split

Require [do not require] all clauses in a definition to hold as definitional equalities unless marked CATCHALL (see Case trees).

Default: --no-exact-split


Default records to no-eta-equality (see Eta-expansion).


New in version 2.6.1.

Disable pattern matching on @♭ arguments (see Pattern Matching on @♭).


Disable pattern matching completely.


Overrides a global --without-K in a file (see Without K).


Disables definitions using Streicher’s K axiom (see Without K).


New in version 2.6.1.

Prevent interactive case splitting from replacing variables with dot patterns (see Dot patterns).

Search depth and instances


Set instance search depth to N (default: 500; see Instance Arguments),


Set maximum depth for pattern match inversion to N (default: 50). Should only be needed in pathological cases.


Allow termination checker to count decrease/increase upto N (default: 1; see Termination Checking).

--overlapping-instances, --no-overlapping-instances

Consider [do not consider] recursive instance arguments during pruning of instance candidates.

Default: --no-overlapping-instances

Other features


Enable double-checking of all terms using the internal typechecker.

--guardedness, --no-guardedness

Enable [disable] constructor-based guarded corecursion (see Coinduction).

The option --guardedness is inconsistent with sized types and it is turned off by --safe (but can be turned on again, as long as not also --sized-types is on).

Default: --guardedness

--irrelevant-projections, --no-irrelevant-projections

New in version 2.5.4.

Enable [disable] projection of irrelevant record fields (see Irrelevance). The option --irrelevant-projections makes Agda inconsistent.

Default (since version 2.6.1): --no-irrelevant-projections


Turn on automatic compile-time inlining. See The INLINE and NOINLINE pragmas for more information.


Disable automatic compile-time inlining (default). Only definitions marked INLINE will be inlined.


Disable reduction using the Agda Abstract Machine.


Disable call-by-need evaluation in the Agda Abstract Machine.


Disable the forcing optimisation. Since Agda 2.6.1 is a pragma option.


Always expand Pattern Synonyms during printing. With this option enabled you can use pattern synonyms freely, but Agda will not use any pattern synonyms when printing goal types or error messages, or when generating patterns for case splits.


Disable the syntactic equality shortcut in the conversion checker.


Disable postulates, unsafe OPTIONS pragmas and primTrustMe. Turns off --sized-types and --guardedness (at most one can be turned back on again) (see Safe Agda).

--sized-types, --no-sized-types

Enable [disable] sized types (see Sized Types).

The option --sized-types is inconsistent with constructor-based guarded corecursion and it is turned off by --safe (but can be turned on again, as long as not also --guardedness is on).

Default: --sized-types


Ignore universe levels (this makes Agda inconsistent; see type-in-type).


Enable typing rule Setω : Setω (this makes Agda inconsistent; see omega-in-omega).

--universe-polymorphism, --no-universe-polymorphism

Enable [disable] universe polymorphism (see Universe Levels).

Default: --universe-polymorphism

--cumulativity, --no-cumulativity

New in version 2.6.1.

Enable [disable] cumulative subtyping of universes, i.e. if A : Set i then also A : Set j for all j >= i. Implies –subtyping.

Default: --no-cumulativity

--subtyping, --no-subtyping

New in version 2.6.1.

Enable [disable] subtyping rules globally, including subtyping for irrelevance, erasure (@0) and flat (@♭) modalities.

Default: --no-subtyping


New in version 2.6.2.

Disable the implicit statement open import Agda.Primitive using (Set; Prop) at the start of each top-level Agda module.


The -W or --warning option can be used to disable or enable different warnings. The flag -W error (or --warning=error) can be used to turn all warnings into errors, while -W noerror turns this off again.

A group of warnings can be enabled by -W {group}, where group is one of the following:


All of the existing warnings.


Default warning level


Ignore all warnings.

The command agda --help=warning provides information about which warnings are turned on by default.

Individual warnings can be turned on and off by -W {Name} and -W {noName} respectively. The flags available are:


RHS given despite an absurd pattern in the LHS.


Attempt to generalize over sort metas in ‘variable’ declaration.


Importing a file not using e.g. --safe from one which does.


Failed coverage checks.


Failed exact split checks.


Feature deprecation.


Empty abstract blocks.


Empty instance blocks.


Empty macro blocks.


Empty mutual blocks.


Empty postulate blocks.


Empty primitive blocks.


Empty private blocks.


Empty REWRITE pragmas.


Illformed as-clauses in import statements.


Importing a file using e.g. :option;`–cubical` into one which doesn’t.


Instance arguments whose type does not end in a named or variable type are never considered by instance search.


Instance arguments with explicit arguments are never considered by instance search.


Instance declarations with explicit arguments are never considered by instance search.


CATCHALL pragmas before a non-function clause.


No positivity checking pragmas before non-data`, record or mutual blocks.


Termination checking pragmas before non-function or mutual blocks.


Inversions of pattern-matching failed due to exhausted inversion depth.


Unknown field in library file.


Names declared without an accompanying definition.


Names mentioned in an import statement which are not exported by the module in question.


Declarations not allowed in a mutual block.


Failed strict positivity checks.


Deprecated BUILTIN pragmas.


Multi-line comments spanning one or more literate text blocks.


Polarity pragmas for non-postulates.


COMPILE pragmas not allowed in safe mode.


COMPILE pragma targeting an erased symbol.


NO_TERMINATION_CHECK pragmas are deprecated.


Failed confluence checks while computing overlap.


Failed confluence checks while joining critical pairs.


NON_TERMINATING pragmas with the safe flag.


NO_POSITIVITY_CHECK pragmas with the safe flag.


NO_UNIVERSE_CHECK pragmas with the safe flag.


POLARITY pragmas with the safe flag.


postulate blocks with the safe flag


Unsafe OPTIONS pragmas with the safe flag.


TERMINATING pragmas with the safe flag.


primEraseEquality used with the safe and without-K flags.


Repeated variable name in telescope.


Failed termination checks.


Mixfix names without an associated fixity declaration.


Names not declared in the same scope as their syntax or fixity declaration.


Names not declared in the same scope as their polarity pragmas.


Unreachable function clauses.


Unsolved constraints.


Unsolved interaction meta variables.


Unsolved meta variables.


abstract blocks where they have no effect.


INLINE pragmas where they have no effect.


instance blocks where they have no effect.


private blocks where they have no effect.


public blocks where they have no effect.


primEraseEquality used with the without-K flags.


Terms marked as eligible for instance search should end with a name.


Run Agda with all warnings enabled, except for warnings about empty abstract blocks:

agda -W all --warning=noEmptyAbstract file.agda

Run Agda on a file which uses the standard library. Note that you must have already created a libraries file as described in Library Management

agda -l standard-library -i. file.agda

(Or if you have added standard-library to your defaults file, simply agda file.agda)

Consistency checking of options used

Agda checks that options used in imported modules are consistent with each other.

An infective option is an option that if used in one module, must be used in all modules that depend on this module. The following options are infective:

A coinfective option is an option that if used in one module, must be used in all modules that this module depends on. The following options are coinfective:

Agda records the options used when generating an interface file. If any of the following options differ when trying to load the interface again, the source file is re-typechecked instead: