Table of Contents



You can create a script to automate a sequence of iPXE commands. Any command that can be typed at the iPXE command line can also be used in a script. You can find a full list of commands in the iPXE command reference.

An iPXE script is a plain text file starting with the magic line #!ipxe and containing a sequence of iPXE commands. For example, here is a simple script that acquires an IP address via DHCP and then boots the iPXE demonstration image:


Here is another simple script that creates a VLAN and then boots from it:

  vcreate --tag 24 net0
  autoboot net0-24

Here is a slightly more sophisticated script that persistently retries DHCP until it succeeds in obtaining a boot filename:

  dhcp && isset ${filename} || goto retry_dhcp
  echo Booting from ${filename}
  chain ${filename}

You can create an iPXE script using any text editor, such as emacs, or vi, or even Windows Notepad. An iPXE script does not need to have any particular file extension (such as .txt or .ipxe); iPXE will recognise it as a script provided that it starts with the magic line #!ipxe.1)

Flow control

You can use the goto command to jump to a predefined script label. You can define a label using

A flowchart


and jump to this label using

  goto label

For example:

  echo Hello world
  goto loop

You can use the && and || operators to conditionally execute commands depending on the status of previous commands. For example:

  dhcp && echo DHCP succeeded
  dhcp || echo DHCP failed

These operators can usefully be combined with the goto command to implement simple conditional flow control. For example, to keep retrying DHCP until it succeeds:

  dhcp || goto retry_dhcp

You can use the ; operator to execute commands regardless of the status of previous commands. For example:

  echo IP address: ${net0/ip} ; echo Subnet mask: ${net0/netmask}

You can terminate a script at any point using the exit command.

Error handling


iPXE will terminate a script immediately if any line of the script fails. For example, if you have the script:


then the script will terminate immediately if the dhcp command fails, without proceeding to the next line. You can override this behaviour using the || operator:

  dhcp ||

In this example, the empty command after the || operator is treated as “do nothing, successfully” (similar to /bin/true on a Unix-like operating system). Even if the dhcp command fails, the overall status of this line of the script will therefore always be “successful”.


You can start a comment using the # symbol. For example:

  # Obtain an address using DHCP
  dhcp || goto retry # Keep retrying indefinitely

Advanced topics


Embedded scripts

You can embed a script within iPXE to override its default behaviour. For example, you may wish to build a version of iPXE containing an embedded script that uses DHCP to obtain an IP address but then boots from a predefined SAN target.

Dynamic scripts

An iPXE script does not have to be a static text file. For example, you could direct iPXE to boot from the URL${net0/mac}&asset=${asset:uristring}

which would expand to a URL such as

The boot.php program running on the web server could dynamically generate a script based on the information provided in the URL. For example, boot.php could look up the asset tag in a MySQL database to determine the correct iSCSI target to boot from, and then dynamically generate a script such as

  set initiator-iqn
1) For the sake of backwards compatibility, iPXE will also recognise legacy gPXE scripts starting with the magic line #!gpxe. However, gPXE is not capable of running iPXE scripts, since the iPXE script language is substantially more advanced than the gPXE script language.