config.yaml¶

If not specified via the command line, the main configuration file config.yaml for OctoPrint is expected in its settings folder, which unless defined differently via the command line is located at ~/.octoprint on Linux, at %APPDATA%/OctoPrint on Windows and at ~/Library/Application Support/OctoPrint on macOS. If the file is not there, you can just create it - it will only get created by OctoPrint once you save settings that deviate from the default settings.

Note that many of these settings are available from the “Settings” menu in OctoPrint itself. They can also be configured via config command line interface.

Access Control¶

Defaults¶

accessControl:
  addRemoteUsers: false
  autologinAs: null
  autologinHeadsupAcknowledged: false
  autologinLocal: false
  checkBasicAuthenticationPassword: true
  defaultReauthenticationTimeout: 5
  groupManager: octoprint.access.groups.FilebasedGroupManager
  groupfile: null
  localNetworks:
  - 127.0.0.0/8
  - ::1/128
  permissionManager: octoprint.access.permissions.PermissionManager
  remoteGroupsHeader: REMOTE_GROUPS
  remoteGroupsMapping: {}
  remoteUserHeader: REMOTE_USER
  salt: null
  sessionStaleAfter: 15
  trustBasicAuthentication: false
  trustRemoteGroups: false
  trustRemoteUser: false
  userManager: octoprint.access.users.FilebasedUserManager
  userfile: null

Data model¶

Name	Type	Description	Default
`salt`	`str`	Secret salt used for password hashing. DO NOT TOUCH! If changed you will no longer be able to log in with your existing accounts. Default unset, generated on first run.	unset
`userManager`	`str`	The user manager implementation to use for accessing user information. Currently only a filebased user manager is implemented which stores configured accounts in a YAML file (Default: `users.yaml` in the default configuration folder).	`'octoprint.access.users.FilebasedUserManager'`
`groupManager`	`str`	The group manager implementation to use for accessing group information. Currently only a filebased user manager is implemented which stores configured groups in a YAML file (Default: `groups.yaml` in the default configuration folder).	`'octoprint.access.groups.FilebasedGroupManager'`
`permissionManager`	`str`	The permission manager implementation to use.	`'octoprint.access.permissions.PermissionManager'`
`userfile`	`str`	The YAML user file to use. If left out defaults to `users.yaml` in the default configuration folder.	unset
`groupfile`	`str`	The YAML group file to use. If left out defaults to `groups.yaml` in the default configuration folder.	unset
`autologinLocal`	`bool`	If set to `true`, will automatically log on clients originating from any of the networks defined in `localNetworks` as the user defined in `autologinAs`.	`False`
`localNetworks`	`list[str]`	A list of networks or IPs for which an automatic logon as the user defined in `autologinAs` will take place. If available OctoPrint will evaluate the `X-Forwarded-For` HTTP header for determining the client’s IP address. Defaults to anything originating from localhost.	`['127.0.0.0/8', '::1/128']`
`autologinAs`	`str`	The name of the user to automatically log on clients originating from `localNetworks` as. Must be the name of one of your configured users.	unset
`autologinHeadsupAcknowledged`	`bool`	Whether the user has acknowledged the heads-up about the importance of a correct reverse proxy configuration in the presence of autologin.	`False`
`trustBasicAuthentication`	`bool`	Whether to trust Basic Authentication headers. If you have setup Basic Authentication in front of OctoPrint and the user names you use there match OctoPrint accounts, by setting this to `true` users will be logged into OctoPrint as the user during Basic Authentication. ONLY ENABLE THIS if your OctoPrint instance is only accessible through a connection locked down through Basic Authentication!	`False`
`checkBasicAuthenticationPassword`	`bool`	Whether to also check the password provided through Basic Authentication, if the Basic Authentication header is to be trusted. Disabling this will only match the user name in the Basic Authentication header and login the user without further checks, thus disable with caution.	`True`
`trustRemoteUser`	`bool`	Whether to trust remote user headers. If you have setup authentication in front of OctoPrint and the user names you use there match OctoPrint accounts, by setting this to true users will be logged into OctoPrint as the user provided in the header. ONLY ENABLE THIS if your OctoPrint instance is only accessible through a connection locked down through an authenticating reverse proxy!	`False`
`remoteUserHeader`	`str`	Header used by the reverse proxy to convey the authenticated user.	`'REMOTE_USER'`
`trustRemoteGroups`	`bool`	Whether to trust remote groups headers. If you have setup authentication in front of OctoPrint and the groups names you use there match OctoPrint accounts, by setting this to `true` the user’s groups will be set to the groups provided in the header. ONLY ENABLE THIS if your OctoPrint instance is only accessible through a connection locked down through an authenticating reverse proxy!	`False`
`remoteGroupsHeader`	`str`	Header used by the reverse proxy to convey the authenticated user’s groups.	`'REMOTE_GROUPS'`
`remoteGroupsMapping`	`dict[str, str]`	Mapping from groups in the header to groups in OctoPrint.	`{}`
`addRemoteUsers`	`bool`	If a remote user is not found, add them. Use this only if all users from the remote system may use OctoPrint.	`False`
`defaultReauthenticationTimeout`	`int`	Default timeout after which to require reauthentication by a user for dangerous changes, in minutes. Defaults to 5 minutes. Set to 0 to disable reauthentication requirements (SECURITY IMPACT!).	`5`
`sessionStaleAfter`	`int`	Default time after which to consider a session stale due to no activity and to remove it.	`15`

API¶

Settings for the REST API.

Defaults¶

api:
  allowCrossOrigin: false
  apps: {}
  key: null

Data model¶

Name	Type	Description	Default
`key`	`str`	Global API key, deprecated, use User API keys instead. Unset by default, will be generated on first run.	unset
`apps`	`dict[str, str]`		`{}`
`allowCrossOrigin`	`bool`	Whether to allow cross origin access to the API or not.	`False`

Appearance¶

Use the following settings to tweak OctoPrint’s appearance a bit to better distinguish multiple instances/printers appearance or to modify the order and presence of the various UI components.

Defaults¶

appearance:
  closeModalsWithClick: true
  color: default
  colorIcon: true
  colorTransparent: false
  components:
    disabled:
      about: []
      generic: []
      navbar: []
      settings: []
      sidebar: []
      tab: []
      usersettings: []
      wizard: []
    order:
      about:
      - about
      - plugin_pi_support
      - supporters
      - authors
      - changelog
      - license
      - thirdparty
      - plugin_pluginmanager
      - plugin_achievements
      - plugin_achievements_2
      - systeminfo
      generic: []
      navbar:
      - settings
      - systemmenu
      - plugin_announcements
      - plugin_logging_seriallog
      - plugin_logging_plugintimingslog
      - plugin_pi_support
      - plugin_health_check
      - login
      settings:
      - section_printer
      - serial
      - printerprofiles
      - temperatures
      - terminalfilters
      - gcodescripts
      - section_features
      - features
      - webcam
      - accesscontrol
      - plugin_gcodeviewer
      - api
      - plugin_appkeys
      - section_octoprint
      - server
      - folders
      - appearance
      - plugin_logging
      - plugin_pluginmanager
      - plugin_softwareupdate
      - plugin_announcements
      - plugin_eventmanager
      - plugin_backup
      - plugin_tracking
      - plugin_errortracking
      - plugin_pi_support
      sidebar:
      - plugin_firmware_check_warning
      - plugin_firmware_check_info
      - connection
      - state
      - files
      tab:
      - temperature
      - control
      - plugin_gcodeviewer
      - terminal
      - timelapse
      usersettings:
      - access
      - interface
      wizard:
      - plugin_softwareupdate_update
      - plugin_backup
      - plugin_corewizard_acl
      - plugin_corewizard_onlinecheck
  defaultLanguage: _default
  fuzzyTimes: true
  name: ''
  showFahrenheitAlso: false
  showInternalFilename: true

Data model¶

Name	Type	Description	Default
`name`	`str`	Use this to give your OctoPrint instance a name. It will be displayed in the title bar (as “<Name> [OctoPrint]”) and in the navigation bar (as “OctoPrint: <>”)	`''`
`color`	`str`	Use this to color the navigation bar. Valid values: `blue`, `default`, `green`, `orange`, `red`, `violet`, `yellow`.	`'default'`
`colorTransparent`	`bool`	Makes the color of the navigation bar “transparent”. In case your printer uses acrylic for its frame 😉.	`False`
`colorIcon`	`bool`		`True`
`defaultLanguage`	`str`	Default language of OctoPrint. If left unset OctoPrint will try to match up available languages with the user’s browser settings.	`'_default'`
`showFahrenheitAlso`	`bool`	Show temperatures in Celsius as well as in Fahrenheit.	`False`
`fuzzyTimes`	`bool`	Display fuzzy times for print time estimations.	`True`
`closeModalsWithClick`	`bool`	Allow closing modals with a click outside of them.	`True`
`showInternalFilename`	`bool`	Show the internal filename in the files sidebar, if necessary.	`True`
`components.*`		Configures the order and availability of the UI components.
`components.order.*`		Defines the order of the components within their respective containers.
`components.order.navbar`	`list[str]`	Order of navbar items.	`['settings', 'systemmenu', 'plugin_announcements', 'plugin_logging_seriallog', 'plugin_logging_plugintimingslog', 'plugin_pi_support', 'plugin_health_check', 'login']`
`components.order.sidebar`	`list[str]`	Order of sidebar items.	`['plugin_firmware_check_warning', 'plugin_firmware_check_info', 'connection', 'state', 'files']`
`components.order.tab`	`list[str]`	Order of tabs.	`['temperature', 'control', 'plugin_gcodeviewer', 'terminal', 'timelapse']`
`components.order.settings`	`list[str]`	Order of settings.	`['section_printer', 'serial', 'printerprofiles', 'temperatures', 'terminalfilters', 'gcodescripts', 'section_features', 'features', 'webcam', 'accesscontrol', 'plugin_gcodeviewer', 'api', 'plugin_appkeys', 'section_octoprint', 'server', 'folders', 'appearance', 'plugin_logging', 'plugin_pluginmanager', 'plugin_softwareupdate', 'plugin_announcements', 'plugin_eventmanager', 'plugin_backup', 'plugin_tracking', 'plugin_errortracking', 'plugin_pi_support']`
`components.order.usersettings`	`list[str]`	Order of user settings.	`['access', 'interface']`
`components.order.wizard`	`list[str]`	Order of wizards.	`['plugin_softwareupdate_update', 'plugin_backup', 'plugin_corewizard_acl', 'plugin_corewizard_onlinecheck']`
`components.order.about`	`list[str]`	Order of about dialog items.	`['about', 'plugin_pi_support', 'supporters', 'authors', 'changelog', 'license', 'thirdparty', 'plugin_pluginmanager', 'plugin_achievements', 'plugin_achievements_2', 'systeminfo']`
`components.order.generic`	`list[str]`	Order of generic items.	`[]`
`components.disabled.*`		Disabled components per container. If a component is included here it will not be included in OctoPrint’s UI at all. Note that this might mean that critical functionality will not be available if no replacement is registered.
`components.disabled.navbar`	`list[str]`	Disabled navbar items.	`[]`
`components.disabled.sidebar`	`list[str]`	Disabled sidebar items.	`[]`
`components.disabled.tab`	`list[str]`	Disabled tabs.	`[]`
`components.disabled.settings`	`list[str]`	Disabled settings.	`[]`
`components.disabled.usersettings`	`list[str]`	Disabled user settings.	`[]`
`components.disabled.wizard`	`list[str]`	Disabled wizards.	`[]`
`components.disabled.about`	`list[str]`	Disabled about dialog items.	`[]`
`components.disabled.generic`	`list[str]`	Disabled generic items.	`[]`

Notes¶

Note

By modifying the components > order lists you may reorder OctoPrint’s UI components as you like. You can also inject Plugins at another than their default location in their respective container by adding the entry plugin_<plugin identifier> where you want them to appear.

Example: If you want the tab of the Hello World Plugin to appear as the first tab in OctoPrint, you’d need to redefine components > order > tab by including something like this in your config.yaml:

appearance:
  components:
    order:
      tab:
      - plugin_helloworld

OctoPrint will then display the tabs in the order plugin_helloworld, temperature, control, plugin_gcodeviewer, terminal, timelapse plus any other plugins.

Controls¶

controls is a list, with each entry in the list being a dictionary describing either a control or a container.

Defaults¶

controls: []

Data Model¶

Controls

Name	Type	Description	Default
`name`	`str`	The name of the control, will be displayed either on the button if it’s a control sending a command or as a label for controls which only display output.	required
`command`	`str`	A single GCODE command to send to the printer. Will be rendered as a button which sends the command to the printer upon click. The button text will be the value of the `name` attribute. Mutually exclusive with `commands` and `script`. The rendered button be disabled if the printer is currently offline or printing or alternatively if the requirements defined via the `enabled` attribute are not met.	unset
`commands`	`list[str]`	A list of GCODE commands to send to the printer. Will be rendered as a button which sends the commands to the printer upon click. The button text will be the value of the `name` attribute. Mutually exclusive with `command` and `script`. The rendered button will be disabled if the printer is currently offline or printing or alternatively if the requirements defined via the `enabled` attribute are not met.	unset
`script`	`str`	The name of a full blown GCODE script to send to the printer. Will be rendered as a button which sends the script to the printer upon click. The button text will be the value of the `name` attribute. Mutually exclusive with `command` and `commands`. The rendered button will be disabled if the printer is currently offline or printing or alternatively if the requirements defined via the `enabled` attribute are not met. Values of input parameters will be available in the template context under the `parameter` variable (e.g. an input parameter `speed` will be available in the script template as `parameter.speed`). On top of that all other variables defined in the GCODE template context will be available.	unset
`javascript`	`str`	A JavaScript snippet to be executed when the button rendered for `command` or `commands` is clicked. This allows to override the direct sending of the command or commands to the printer with more sophisticated behaviour. The JavaScript snippet is `eval`’d and processed in a context where the control it is part of is provided as local variable `data` and the `ControlViewModel` is available as `self`.	unset
`additionalClasses`	`str`	Additional classes to apply to the button of a `command`, `commands`, `script` or `javascript` control, other than the default `btn`. Can be used to visually style the button, e.g. set to `btn-danger` to turn the button red.	unset
`enabled`	`str`	A JavaScript snippet returning either `true` or `false` determining whether the control should be enabled or not. This allows to override the default logic for the enable state of the control (disabled if printer is offline). The JavaScript snippet is `eval`’d and processed in a context where the control it is part of is provided as local variable `data` and the `ControlViewModel` is available as `self`.	unset
`input`	`list[Input]`	A list of definitions of input parameters for a `command` or `commands`, to be rendered as additional input fields. `command`/`commands` may contain placeholders to be replaced by the values obtained from the user for the defined input fields.	`[]`
`regex`	`str`	A regular expression to match against lines received from the printer to retrieve information from it (e.g. specific output). Together with `template` this allows rendition of received data from the printer within the UI.	unset
`template`	`str`	A template to use for rendering the match of `regex`. May contain placeholders in Python Format String Syntax for either named groups within the regex (e.g. `Temperature: {temperature}` for a regex `T:\s(?P<temperature>\d+(\.\d)`) or positional groups within the regex (e.g. `Position: X={0}, Y={1}, Z={2}, E={3}` for a regex `X:([0-9.]+) Y:([0-9.]+) Z:([0-9.]+) E:([0-9.]+)`).	unset
`confirm`	`str`	A text to display to the user to confirm his button press. Can be used with sensitive custom controls like changing EEPROM values in order to prevent accidental clicks. The text will be displayed in a confirmation dialog.	unset

Containers

Name	Type	Description	Default
`children`	`list[Union[Container, Control]]`	A list of children controls or containers contained within this container.	`[]`
`name`	`str`	A name to display above the container, basically a section header.	unset
`layout`	`str`	The layout to use for laying out the contained children, either from top to bottom (`vertical`) or from left to right (`horizontal`). Valid values: `horizontal`, `horizontal_grid`, `vertical`.	`'vertical'`

Inputs

Name	Type	Description	Default
`name`	`str`	Name to display for the input field.	required
`parameter`	`str`	Internal parameter name for the input field, used as a placeholder in `command`/`commands`.	required
`default`	`Union[str, int, float, bool]`	Default value for the input field.	required
`slider`	`ControlSliderInputConfig`	If this attribute is included, instead of an input field a slider control will be rendered.	unset

Sliders

Name	Type	Description	Default
`min`	`int`	Minimum value of the slider.	`0`
`max`	`int`	Maximum value of the slider.	`255`
`step`	`int`	Step size per slider tick.	`1`

Example¶

controls:
  - name: Fan
    layout: horizontal
    children:
      - name: Enable Fan
        type: parametric_command
        command: M106 S%(speed)s
        input:
          - name: Speed (0-255)
            parameter: speed
            default: 255
      - name: Disable Fan
        type: command
        command: M107

Development settings¶

The following settings are only relevant to you if you want to do OctoPrint development.

Defaults¶

devel:
  cache:
    enabled: true
    preemptive: true
  enableCsrfProtection: true
  enableRateLimiter: true
  pluginTimings: false
  showLoadingAnimation: true
  sockJsConnectTimeout: 30.0
  stylesheet: css
  useFrozenDictForPrinterState: true
  webassets:
    bundle: true
    clean_on_startup: true
    minify: true
    minify_plugins: false

Data model¶

Name	Type	Description	Default
`stylesheet`	`str`	Settings for stylesheet preference. OctoPrint will prefer to use the stylesheet type specified here. Usually (on a production install) that will be the compiled `css` (default). Developers may specify `less` here too. Valid values: `css`, `less`.	`'css'`
`cache.*`		Settings for OctoPrint’s internal caching.
`cache.enabled`	`bool`	Whether to enable caching. Defaults to true. Setting it to false will cause the UI to always be fully rerendered on request to `/` on the server.	`True`
`cache.preemptive`	`bool`	Whether to enable the preemptive cache.	`True`
`webassets.*`		Settings for OctoPrint’s web asset merging and minifying.
`webassets.bundle`	`bool`	If set to `true`, OctoPrint will merge all JS, all CSS and all Less files into one file per type to reduce request count. Setting it to `false` will load all assets individually. Note: if this is set to `false`, no minification will take place regardless of the `minify` setting.	`True`
`webassets.clean_on_startup`	`bool`	Whether to delete generated web assets on server startup (forcing a regeneration).	`True`
`webassets.minify`	`bool`	If set to `true`, OctoPrint will minify the core and library javascript assets. Note: if `bundle` is set to `false`, no minification will take place regardless of this setting.	`True`
`webassets.minify_plugins`	`bool`	If set to `true`, OctoPrint will also minify the third party plugin javascript assets. Note: if `bundle` or `minify` are set to `false`, no minification of the plugin assets will take place regardless of this setting.	`False`
`useFrozenDictForPrinterState`	`bool`	Whether to use the `frozendict` type for tracking the printer state.	`True`
`showLoadingAnimation`	`bool`	Enable or disable the loading animation.	`True`
`sockJsConnectTimeout`	`float`	Connection timeout for the SockJS connection.	`30`
`pluginTimings`	`bool`	Whether to enable the creation of plugin_timings.log.	`False`
`enableRateLimiter`	`bool`	Enable or disable the rate limiter. Careful, disabling this reduces security (SECURITY IMPACT!).	`True`
`enableCsrfProtection`	`bool`	Enable or disable the CSRF protection. Careful, disabling this reduces security (SECURITY IMPACT!).	`True`

Estimation¶

Defaults¶

estimation:
  printTime:
    forceDumbAfterMin: 30.0
    forceDumbFromPercent: 0.3
    stableThreshold: 60
    statsWeighingUntil: 0.5
    validityRange: 0.15

Data model¶

Name	Type	Description	Default
`printTime.*`		Parameters for the print time estimation during an ongoing print job.
`printTime.statsWeighingUntil`	`float`	Until which percentage to do a weighted mixture of statistical duration (analysis or past prints) with the result from the calculated estimate if that’s already available. Utilized to compensate for the fact that the earlier in a print job, the least accuracy even a stable calculated estimate provides.	`0.5`
`printTime.validityRange`	`float`	Range the assumed percentage (based on current estimated statistical, calculated or mixed total vs elapsed print time so far) needs to be around the actual percentage for the result to be used.	`0.15`
`printTime.forceDumbFromPercent`	`float`	If no estimate could be calculated until this percentage and no statistical data is available, use dumb linear estimate. Value between 0 and 1.0.	`0.3`
`printTime.forceDumbAfterMin`	`float`	If no estimate could be calculated until this many minutes into the print and no statistical data is available, use dumb linear estimate.	`30.0`
`printTime.stableThreshold`	`int`	Average fluctuation between individual calculated estimates to consider in stable range. Seconds of difference.	`60`

Events¶

Use the following settings to add shell/gcode commands to be executed on certain events.

Defaults¶

event:
  enabled: true
  subscriptions: []

Data model¶

Name	Type	Description	Default
`enabled`	`bool`	Whether event subscriptions should be enabled or not.	`True`
`subscriptions[]`		A list of event subscriptions.
`subscriptions[].event`	`str`	The event to subscribe to.	required
`subscriptions[].name`	`str`	The event name to show on the UI.	unset
`subscriptions[].command`	`str`	The command to execute when the event is triggered, either a GCODE or a system command.	required
`subscriptions[].type`	`str`	The type of the command. Valid values: `gcode`, `system`.	required
`subscriptions[].enabled`	`bool`	Whether the event subscription should be enabled.	`True`
`subscriptions[].debug`	`bool`	If set to `true`, OctoPrint will log the command after performing all placeholder replacements.	`False`

The individual event subscriptions have to be defined like this:

Name	Type	Description	Default
`event`	`str`	The event to subscribe to.	required
`name`	`str`	The event name to show on the UI.	unset
`command`	`str`	The command to execute when the event is triggered, either a GCODE or a system command.	required
`type`	`str`	The type of the command. Valid values: `gcode`, `system`.	required
`enabled`	`bool`	Whether the event subscription should be enabled.	`True`
`debug`	`bool`	If set to `true`, OctoPrint will log the command after performing all placeholder replacements.	`False`

Notes¶

Note

For debugging purposes, you can also add an additional property debug to your event subscription definitions that if set to true will make the event handler print a log line with your subscription’s command after performing all placeholder replacements. Example:

events:
  subscriptions:
  - event: Startup
    command: "logger 'OctoPrint started up'"
    type: system
    debug: true

This will be logged in OctoPrint’s logfile as

Executing System Command: logger 'OctoPrint started up'

Example¶

events:
subscriptions:
  # example event consumer that prints a message to the system log if the printer is disconnected
  - event: Disconnected
    command: "logger 'Printer got disconnected'"
    type: system

  # example event consumer that queries printer information from the firmware, prints a "Connected"
  # message to the LCD and homes the print head upon established printer connection, disabled though
  - event: Connected
    command: M115,M117 printer connected!,G28
    type: gcode
    enabled: False

Feature¶

Use the following settings to enable or disable OctoPrint features.

Defaults¶

feature:
  autoUppercaseBlacklist:
  - M117
  - M118
  - M707
  - M708
  enableDragDropUpload: true
  enforceReallyUniversalFilenames: false
  fileDeleteConfirmation: true
  g90InfluencesExtruder: false
  keyboardControl: true
  modelSizeDetection: true
  pollWatched: false
  printCancelConfirmation: true
  printStartConfirmation: false
  rememberFileFolder: false
  sdSupport: true
  temperatureGraph: true
  uploadOverwriteConfirmation: true

Data model¶

Name	Type	Description	Default
`temperatureGraph`	`bool`	Whether to enable the temperature graph in the UI or not.	`True`
`sdSupport`	`bool`	Specifies whether support for SD printing and file management should be enabled.	`True`
`keyboardControl`	`bool`	Whether to enable the keyboard control feature in the control tab.	`True`
`pollWatched`	`bool`	Whether to actively poll the watched folder (`true`) or to rely on the OS’s file system notifications instead (`false`).	`False`
`modelSizeDetection`	`bool`	Whether to enable model size detection and warning (`true`) or not (`false`).	`True`
`rememberFileFolder`	`bool`	Whether to remember the selected folder on the file manager.	`False`
`printStartConfirmation`	`bool`	Whether to show a confirmation on print start (`true`) or not (`false`).	`False`
`printCancelConfirmation`	`bool`	Whether to show a confirmation on print cancelling (`true`) or not (`false`).	`True`
`uploadOverwriteConfirmation`	`bool`	Whether to show a confirmation when about to overwrite an uploaded file.	`True`
`fileDeleteConfirmation`	`bool`	Whether to show a confirmation when about to delete a file.	`True`
`autoUppercaseBlacklist`	`list[str]`	Commands that should never be auto-uppercased when sent to the printer through the Terminal tab.	`['M117', 'M118', 'M707', 'M708']`
`g90InfluencesExtruder`	`bool`	Whether `G90`/`G91` also influence absolute/relative mode of extruders.	`False`
`enforceReallyUniversalFilenames`	`bool`	Replace all special characters and spaces with text equivalent to make them universally compatible. Most OS filesystems work fine with unicode characters, but just in case you can revert to the older behaviour by setting this to `true`.	`False`
`enableDragDropUpload`	`bool`	Enable drag and drop upload overlay	`True`

Folder¶

Use the following settings to set custom paths for folders used by OctoPrint.

Defaults¶

folder:
  data: null
  generated: null
  logs: null
  plugins: null
  printerProfiles: null
  scripts: null
  slicingProfiles: null
  timelapse: null
  timelapse_tmp: null
  translations: null
  uploads: null
  virtualSd: null
  watched: null

Data model¶

Name	Type	Description	Default
`uploads`	`str`	Absolute path where to store gcode uploads. Defaults to the `uploads` folder in OctoPrint’s base folder.	unset
`timelapse`	`str`	Absolute path where to store finished timelase recordings. Defaults to the `timelapse` folder in OctoPrint’s base folder.	unset
`timelapse_tmp`	`str`	Absolute path where to store temporary timelapse snapshots. Defaults to the `timelapse/tmp` folder in OctoPrint’s base folder.	unset
`logs`	`str`	Absolute path where to store logs. Defaults to the `logs` folder in OctoPrint’s base folder.	unset
`virtualSd`	`str`	Absolute path where to store the virtual printer’s SD card files. Defaults to the `virtualSd` folder in OctoPrint’s base folder.	unset
`watched`	`str`	Absolute path to the watched folder. Defaults to the `watched` folder in OctoPrint’s base folder.	unset
`plugins`	`str`	Absolute path where to locate and install single file plugins. Defaults to the `plugins` folder in OctoPrint’s base folder.	unset
`slicingProfiles`	`str`	Absolute path where to store slicing profiles. Defaults to the `slicingProfiles` folder in OctoPrint’s base folder.	unset
`printerProfiles`	`str`	Absolute path where to store printer profiles. Defaults to the `printerProfiles` folder in OctoPrint’s base folder.	unset
`scripts`	`str`	Absolute path where to store (GCODE) scripts. Defaults to the `scripts` folder in OctoPrint’s base folder.	unset
`translations`	`str`	Absolute path where to store additional translations. Defaults to the `translations` folder in OctoPrint’s base folder.	unset
`generated`	`str`	Absolute path where to store generated files. Defaults to the `generated` folder in OctoPrint’s base folder.	unset
`data`	`str`	Absolute path where to store additional data. Defaults to the `data` folder in OctoPrint’s base folder.	unset

GCODE Analysis¶

Settings pertaining to the server side GCODE analysis implementation.

gcode_analysis:
  bedZ: 0.0
  maxExtruders: 10
  runAt: idle
  throttle_highprio: 0.0
  throttle_lines: 100
  throttle_normalprio: 0.01

Name	Type	Description	Default
`maxExtruders`	`int`	Maximum number of extruders to support/to sanity check for.	`10`
`throttle_normalprio`	`float`	Pause between each processed GCODE line batch in normal priority mode, seconds.	`0.01`
`throttle_highprio`	`float`	Pause between each processed GCODE line batch in high priority mode (e.g. on fresh uploads), seconds.	`0.0`
`throttle_lines`	`int`	GCODE line batch size.	`100`
`runAt`	`str`	Whether to run the analysis only when idle (not printing), regardless of printing state or never. Valid values: `always`, `idle`, `never`.	`'idle'`
`bedZ`	`float`	Z position considered the location of the bed.	`0.0`

Plugin settings¶

The plugins section is where plugins can store their specific settings. It is also where the installed but disabled plugins are tracked.

plugins:
  _disabled: []
  _flags: {}
  _forcedCompatible: []
  _sortingOrder: {}

Name	Type	Description	Default
`_disabled`	`list[str]`	Identifiers of installed but disabled plugins.	`[]`
`_forcedCompatible`	`list[str]`	Identifiers of plugins for which python compatibility information will be ignored and the plugin considered compatible in any case. Only for development, do NOT use in production.	`[]`
`_sortingOrder`	`dict[str, dict[str, int]]`	Custom sorting of hooks and implementations provided by plugins. Two-tiered dictionary structure, plugin identifier mapping to a dictionary of order overrides mapped by sorting context/hook name.	`{}`
`_flags`	`dict[str, list[str]]`	Configured flags for plugins by plugin identifier.	`{}`

Additionally to the fields listed here, plugins will contain further keys for each plugin that is storing settings itself. The keys will be the plugin’s identifier.

Example¶

plugins:
_disabled:
  - some_plugin
_forcedCompatible:
  - some_other_plugin
_sortingOrder:
  yet_another_plugin:
    octoprint.plugin.ordertest.callback: 1
    StartupPlugin.on_startup: 10
virtual_printer:
  _config_version: 1
  enabled: true

Printer Parameters¶

Defaults¶

printerParameters:
  pauseTriggers: []

Data model¶

Name	Type	Description	Default
`pauseTriggers`	`list[str]`		`[]`

Printer Profiles¶

Defaults settings for printer profiles.

Defaults¶

printerProfiles:
  default: null

Data model¶

Name	Type	Description	Default
`default`	`str`	Name of the printer profile to default to.	unset

Scripts¶

Default scripts and snippets. You’d usually not edit the config.yaml file to adjust those but instead create the corresponding files in ~/.octoprint/scripts/. See GCODE Script.

Defaults¶

scripts:
  gcode:
    afterPrintCancelled: '; disable motors

      M84


      ;disable all heaters

      {% snippet ''disable_hotends'' %}

      {% snippet ''disable_bed'' %}

      ;disable fan

      M106 S0'
    afterPrintDone: null
    afterPrintResumed: null
    afterPrinterConnected: null
    afterToolChange: null
    beforePrintPaused: null
    beforePrintStarted: null
    beforePrinterDisconnected: null
    beforeToolChange: null
    snippets:
      disable_bed: '{% if printer_profile.heatedBed %}M140 S0

        {% endif %}'
      disable_hotends: '{% if printer_profile.extruder.sharedNozzle %}M104 T0 S0

        {% else %}{% for tool in range(printer_profile.extruder.count) %}M104 T{{
        tool }} S0

        {% endfor %}{% endif %}'

Data model¶

Name	Type	Description	Default
`gcode.*`		GCODE scripts configuration
`gcode.afterPrinterConnected`	`str`	Script run after the connection to the printer has been established.	unset
`gcode.beforePrinterDisconnected`	`str`	Script run before the printer gets disconnected.	unset
`gcode.beforePrintStarted`	`str`	Script run before a print job is started.	unset
`gcode.afterPrintCancelled`	`str`	Script run after a print job has been cancelled.	`"; disable motors\nM84\n\n;disable all heaters\n{% snippet 'disable_hotends' %}\n{% snippet 'disable_bed' %}\n;disable fan\nM106 S0"`
`gcode.afterPrintDone`	`str`	Script run after a print job completes.	unset
`gcode.beforePrintPaused`	`str`	Script run on pausing a print job.	unset
`gcode.afterPrintResumed`	`str`	Script run on resuming a print job.	unset
`gcode.beforeToolChange`	`str`	Script run before sending a tool change command to the printer.	unset
`gcode.afterToolChange`	`str`	Script run after sending a tool change command to the printer.	unset
`gcode.snippets`	`dict[str, str]`	Additional snippets that can be used in other scripts.	`{'disable_hotends': '{% if printer_profile.extruder.sharedNozzle %}M104 T0 S0\n{% else %}{% for tool in range(printer_profile.extruder.count) %}M104 T{{ tool }} S0\n{% endfor %}{% endif %}', 'disable_bed': '{% if printer_profile.heatedBed %}M140 S0\n{% endif %}'}`

Serial¶

Use the following settings to configure the serial connection to the printer.

Defaults¶

serial:
  abortHeatupOnCancel: true
  ackMax: 1
  additionalBaudrates: []
  additionalPorts: []
  alwaysSendChecksum: false
  autoconnect: false
  autorefresh: true
  autorefreshInterval: 1
  baudrate: null
  blacklistedBaudrates: []
  blacklistedPorts: []
  blockWhileDwelling: false
  blockedCommands:
  - M0
  - M1
  capabilities:
    autoreport_pos: true
    autoreport_sdstatus: true
    autoreport_temp: true
    busy_protocol: true
    emergency_parser: true
    extended_m20: true
    lfn_write: true
  checksumRequiringCommands:
  - M110
  disableSdPrintingDetection: false
  disconnectOnErrors: true
  emergencyCommands:
  - M112
  - M108
  - M410
  enableShutdownActionCommand: false
  encoding: ascii
  exclusive: true
  externalHeatupDetection: true
  firmwareDetection: true
  helloCommand: M110 N0
  identicalResendsCountdown: 7
  ignoreEmptyPorts: false
  ignoreErrorsFromFirmware: false
  ignoreIdenticalResends: false
  ignoredCommands: []
  lastLineBufferSize: 50
  log: false
  logPositionOnCancel: false
  logPositionOnPause: true
  logResends: true
  longRunningCommands:
  - G4
  - G28
  - G29
  - G30
  - G32
  - M400
  - M226
  - M600
  lowLatency: false
  maxCommunicationTimeouts:
    idle: 2
    long: 5
    printing: 5
  maxConsecutiveResends: 10
  maxNotSdPrinting: 2
  maxWritePasses: 5
  neverSendChecksum: false
  notifySuppressedCommands: warn
  pausingCommands:
  - M0
  - M1
  - M25
  port: null
  repetierTargetTemp: false
  resendRatioStart: 100
  resendRatioThreshold: 10
  sanityCheckTools: true
  sdAlwaysAvailable: false
  sdCancelCommand: M25
  sdLowerCase: false
  sdRelativePath: false
  sendChecksumWithUnknownCommands: false
  sendM112OnError: true
  supportFAsCommand: false
  supportResendsWithoutOk: detect
  supportWait: true
  suppressSecondHello: false
  swallowOkAfterResend: true
  terminalLogSize: 20
  timeout:
    baudrateDetectionPause: 1.0
    communication: 30.0
    communicationBusy: 3.0
    connection: 10.0
    detectionConsecutive: 2.0
    detectionFirst: 10.0
    posAutoreport: 5.0
    positionLogWait: 10.0
    resendOk: 0.5
    sdStatus: 1.0
    sdStatusAutoreport: 1.0
    temperature: 5.0
    temperatureAutoreport: 2.0
    temperatureTargetSet: 2.0
  triggerOkForM29: true
  unknownCommandsNeedAck: false
  useParityWorkaround: detect
  waitForStartOnConnect: false
  waitToLoadSdFileList: true

Data model¶

Name	Type	Description	Default
`port`	`str`	The default port to use to connect to the printer. If unset or set to `AUTO`, the port will be auto-detected.	unset
`baudrate`	`int`	The default baudrate to use to connect to the printer. If unset or set to 0, the baudrate will be auto-detected.	unset
`exclusive`	`bool`	Whether to request exclusive access to the serial port.	`True`
`lowLatency`	`bool`	Whether to request low latency mode on the serial port.	`False`
`autoconnect`	`bool`	Whether to try to automatically connect to the printer on startup.	`False`
`autorefresh`	`bool`	Whether to automatically refresh the port list while no connection is established.	`True`
`autorefreshInterval`	`int`	Interval in seconds at which to refresh the port list while no connection is established.	`1`
`log`	`bool`	Whether to log whole communication to `serial.log` (warning: might decrease performance).	`False`
`timeout.*`		Timeouts used for the serial connection to the printer, you might want to adjust these if you are experiencing connection problems.
`timeout.detectionFirst`	`float`	Timeout during initial detection attempt, in seconds.	`10.0`
`timeout.detectionConsecutive`	`float`	Timeout on consecutive detection attempts, in seconds.	`2.0`
`timeout.connection`	`float`	Timeout for waiting to establish a connection with the selected port, in seconds.	`10.0`
`timeout.communication`	`float`	Timeout during serial communication, in seconds.	`30.0`
`timeout.communicationBusy`	`float`	Timeout during serial communication when busy protocol support is detected, in seconds.	`3.0`
`timeout.temperature`	`float`	Timeout after which to query temperature when no target is set, in seconds.	`5.0`
`timeout.temperatureTargetSet`	`float`	Timeout after which to query temperature when a target is set, in seconds.	`2.0`
`timeout.temperatureAutoreport`	`float`	Autoreporting interval to request for the temperature report, in seconds.	`2.0`
`timeout.sdStatus`	`float`	Timeout after which to query the SD status while SD printing.	`1.0`
`timeout.sdStatusAutoreport`	`float`	Autoreporting interval to request for the SD status report, in seconds.	`1.0`
`timeout.posAutoreport`	`float`	Autoreporting interval to request for the position report, in seconds.	`5.0`
`timeout.resendOk`	`float`	Timeout after which to trigger an internal `ok` after a resend is received (works around a bug present in some firmwares), in seconds.	`0.5`
`timeout.baudrateDetectionPause`	`float`	Pause between baudrate detection attempts, in seconds.	`1.0`
`timeout.positionLogWait`	`float`	Time to wait to receive a position response before considering it unresponded, in seconds.	`10.0`
`maxCommunicationTimeouts.*`		Maximum communication timeouts.
`maxCommunicationTimeouts.idle`	`int`	Max. timeouts when the printer is idle.	`2`
`maxCommunicationTimeouts.printing`	`int`	Max. timeouts when the printer is printing.	`5`
`maxCommunicationTimeouts.long`	`int`	Max. timeouts when a long running command is active.	`5`
`maxWritePasses`	`int`	Maximum number of write attempts to serial during which nothing can be written before the communication with the printer is considered dead and OctoPrint will disconnect with an error.	`5`
`additionalPorts`	`list[str]`	Use this to define additional patterns to consider for serial port listing. Must be a list of valid “glob” pattern	`[]`
`additionalBaudrates`	`list[int]`	Use this to define additional baud rates to offer for connecting to serial ports. Must be a list of valid integers.	`[]`
`blacklistedPorts`	`list[str]`	Serial ports to be ignored by OctoPrint.	`[]`
`blacklistedBaudrates`	`list[int]`	Baudrates to be ignored by OctoPrint.	`[]`
`longRunningCommands`	`list[str]`	Commands which are known to take a long time to be acknowledged by the firmware, e.g. homing, dwelling, auto leveling etc.	`['G4', 'G28', 'G29', 'G30', 'G32', 'M400', 'M226', 'M600']`
`blockedCommands`	`list[str]`	Commands which should not be sent to the printer, e.g. because they are known to block serial communication until physical interaction with the printer as is the case on most firmwares with the default `M0` and `M1`.	`['M0', 'M1']`
`ignoredCommands`	`list[str]`	Commands which should not be sent to the printer and just silently ignored. An example of when you may wish to use this would be to manually change a filament on M600, by using that as a Pausing command.	`[]`
`pausingCommands`	`list[str]`	Commands which should cause OctoPrint to pause any ongoing prints.	`['M0', 'M1', 'M25']`
`emergencyCommands`	`list[str]`	Commands which are considered emergency commands and will be sent immediately, jumping OctoPrint’s internal queues.	`['M112', 'M108', 'M410']`
`checksumRequiringCommands`	`list[str]`	Commands which need to always be send with a checksum.	`['M110']`
`helloCommand`	`str`	Command to send in order to initiate a handshake with the printer.	`'M110 N0'`
`suppressSecondHello`	`bool`	Whether to suppress the second hello command. Might be required for some printer configurations with custom hello commands.	`False`
`disconnectOnErrors`	`bool`	Whether to disconnect from the printer on errors	`True`
`ignoreErrorsFromFirmware`	`bool`	Whether to completely ignore errors from the firmware.	`False`
`terminalLogSize`	`int`	Size of log lines to keep for logging error context.	`20`
`lastLineBufferSize`	`int`		`50`
`logResends`	`bool`	Whether to log resends to octoprint.log or not. Invaluable debug tool without performance impact, leave on if possible please.	`True`
`supportResendsWithoutOk`	`str`	Whether to support resends without follow-up ok. Valid values: `always`, `detect`, `never`.	`'detect'`
`logPositionOnPause`	`bool`	Whether to request and log the current position from the printer on a pause.	`True`
`logPositionOnCancel`	`bool`	Whether to request and log the current position from the printer on a cancel.	`False`
`abortHeatupOnCancel`	`bool`	Whether to send an abort heatup command on cancel.	`True`
`waitForStartOnConnect`	`bool`	Whether OctoPrint should wait for the `start` response from the printer before trying to send commands during connect.	`False`
`waitToLoadSdFileList`	`bool`	Specifies whether OctoPrint should wait to load the SD card file list until the first firmware capability report is processed.	`True`
`alwaysSendChecksum`	`bool`	Specifies whether OctoPrint should send linenumber + checksum with every printer command. Needed for successful communication with Repetier firmware.	`False`
`neverSendChecksum`	`bool`	Specifies whether OctoPrint should never send linenumber + checksum.	`False`
`sendChecksumWithUnknownCommands`	`bool`	Specifies whether OctoPrint should also send linenumber + checksum with commands that are not detected as valid GCODE (as in, they do not match the regular expression `^\s*([GM]\d+\|T)`).	`False`
`unknownCommandsNeedAck`	`bool`	Specifies whether OctoPrint should also use up acknowledgments (`ok`) for commands that are not detected as valid GCODE (as in, they do not match the regular expression `^\s*([GM]\d+\|T)`).	`False`
`sdRelativePath`	`bool`	Specifies whether firmware expects relative paths for selecting SD files.	`False`
`sdAlwaysAvailable`	`bool`	Whether to always assume that an SD card is present in the printer. Needed by some firmwares which don’t report the SD card status properly.	`False`
`sdLowerCase`	`bool`		`False`
`sdCancelCommand`	`str`	Command to send to cancel prints from the printer’s memory.	`'M25'`
`maxNotSdPrinting`	`int`	Maximum number of “Not SD printing” messages to allow before considering a print to have been cancelled by the printer.	`2`
`swallowOkAfterResend`	`bool`	Whether to ignore any additional `ok` after a resend request, which already acts as a negative acknowledgement.	`True`
`repetierTargetTemp`	`bool`	Whether the printer sends repetier style target temperatures in the format `TargetExtr0:<temperature>` instead of attaching that information to the regular `M105` responses.	`False`
`externalHeatupDetection`	`bool`	Whether to enable external heatup detection (to detect heatup triggered e.g. through the printer’s LCD panel or while printing from the printer’s memory). Causes issues with Repetier’s “first ok then response” approach to communication, so disable for printers running Repetier firmware.	`True`
`supportWait`	`bool`	Whether to support `wait` responses from the printer and interpret them as a call to send more commands.	`True`
`ignoreIdenticalResends`	`bool`	Whether to ignore identical resends from the printer (`true`, repetier) or not (`false`).	`False`
`identicalResendsCountdown`	`int`	If `ignoreIdenticalResends` is true, how many consecutive identical resends to ignore.	`7`
`supportFAsCommand`	`bool`	Whether to support `F` on its own as a valid GCODE command (`true`) or not (`false`).	`False`
`firmwareDetection`	`bool`	Whether to attempt to auto detect the firmware of the printer and adjust settings accordingly (`true`) or not and rely on manual configuration (`false`).	`True`
`blockWhileDwelling`	`bool`	Whether to block all sending to the printer while a `G4` (dwell) command is active (`true`, repetier) or not (`false`).	`False`
`useParityWorkaround`	`str`	Whether to use the parity workaround needed for connecting to some printers. Valid values: `always`, `detect`, `never`.	`'detect'`
`maxConsecutiveResends`	`int`	Number of times to allow to resend the same line before the print job gets considered as failed.	`10`
`sendM112OnError`	`bool`	Whether to send an `M112` on encountered errors.	`True`
`disableSdPrintingDetection`	`bool`	Whether to disable the detection of SD print jobs triggered from the printer.	`False`
`ackMax`	`int`	Maximum number of `ok` acknowledgements to keep active. DO NOT TOUCH THIS! Changes can cause completely broken communication.	`1`
`sanityCheckTools`	`bool`	Whether to senity check the tool count.	`True`
`notifySuppressedCommands`	`str`	Whether to notify about any suppressed commands. Valid values: `info`, `never`, `warn`.	`'warn'`
`capabilities.*`
`capabilities.autoreport_temp`	`bool`	Whether to enable temperature autoreport in the firmware if its support is detected.	`True`
`capabilities.autoreport_sdstatus`	`bool`	Whether to enable SD printing autoreport in the firmware if its support is detected.	`True`
`capabilities.autoreport_pos`	`bool`	Whether to enable position autoreport in the firmware if its support is detected.	`True`
`capabilities.busy_protocol`	`bool`	Whether to shorten the communication timeout if the firmware seems to support the busy protocol.	`True`
`capabilities.emergency_parser`	`bool`	Whether to send emergency commands out of band if the firmware seems to support the emergency parser.	`True`
`capabilities.extended_m20`	`bool`	Whether to request extended M20 (file list) output from the firmware if its support is detected.	`True`
`capabilities.lfn_write`	`bool`	Whether to enable long filename support for SD card writes if the firmware reports support for it.	`True`
`resendRatioThreshold`	`int`	Percentage of resend requests among all sent lines that should be considered critical.	`10`
`resendRatioStart`	`int`	Line number on which to start tracking the resend ratio.	`100`
`ignoreEmptyPorts`	`bool`	Whether to ignore if there are no serial ports detected.	`False`
`encoding`	`str`	Encoding to use when talking to a machine. `ascii` limits access to characters 0-127, `latin_1` enables access to the “extended” ascii characters 0-255. Other values can be used, see Python’s standard encodings.	`'ascii'`
`enableShutdownActionCommand`	`bool`	Whether to enable support for the shutdown action command, allowing the printer to shut down OctoPrint and the system it’s running on.	`False`
`triggerOkForM29`	`bool`	Whether to automatically trigger an ok for `M29` (a lot of versions of this command are buggy and the response skips on the ok).	`True`

Server¶

Use the following settings to configure the server.

Defaults¶

server:
  allowFraming: false
  allowedLoginRedirectPaths: []
  commands:
    localPipCommand: null
    serverRestartCommand: null
    systemRestartCommand: null
    systemShutdownCommand: null
  cookies:
    samesite: Lax
    secure: false
  diskspace:
    critical: 209715200
    warning: 524288000
  firstRun: true
  heartbeat: 900
  host: null
  ignoreIncompleteStartup: false
  ipCheck:
    enabled: true
    trustedSubnets: []
  maxSize: 102400
  onlineCheck:
    enabled: null
    host: 1.1.1.1
    interval: 900
    name: octoprint.org
    port: 53
  pluginBlacklist:
    enabled: null
    timeout: 3.05
    ttl: 900
    url: https://plugins.octoprint.org/blacklist.json
  port: 5000
  preemptiveCache:
    exceptions: []
    until: 7
  pythonEolCheck:
    enabled: true
    fallback:
      '3.7':
        date: '2023-06-27'
        last_octoprint: 1.11.*
      '3.8':
        date: '2024-10-31'
        last_octoprint: null
    ttl: 1440
    url: https://get.octoprint.org/python-eol
  reverseProxy:
    hostFallback: null
    hostHeader: X-Forwarded-Host
    portFallback: null
    portHeader: null
    prefixFallback: null
    prefixHeader: X-Script-Name
    schemeFallback: null
    schemeHeader: X-Scheme
    serverFallback: null
    serverHeader: null
    trustLocalhostProxies: true
    trustedProxies: []
  secretKey: null
  seenWizards: {}
  startOnceInSafeMode: false
  uploads:
    maxSize: 1073741824
    nameSuffix: name
    pathSuffix: path

Data model¶

Name	Type	Description	Default
`host`	`str`	Use this option to define the host to which to bind the server. If unset, OctoPrint will attempt to bind on all available interfaces, IPv4 and v6 unless either is disabled.	unset
`port`	`int`	Use this option to define the port to which to bind the server.	`5000`
`firstRun`	`bool`	If this option is `true`, OctoPrint will show the First Run wizard and set the setting to false after that completes.	`True`
`startOnceInSafeMode`	`bool`	If this option is `true`, OctoPrint will enable safe mode on the next server start and reset the setting to false	`False`
`ignoreIncompleteStartup`	`bool`	Set this to `true` to make OctoPrint ignore incomplete startups. Helpful for development.	`False`
`seenWizards`	`dict[str, str]`	Tracking of seen wizards and versions. You should usually not have to touch this.	`{}`
`secretKey`	`str`	Secret key for encrypting cookies and such, randomly generated on first run.	unset
`heartbeat`	`int`	Interval in which to log the server heartbeat, defaults to every 15min.	`900`
`reverseProxy.*`		Settings if OctoPrint is running behind a reverse proxy (haproxy, nginx, apache, …) that doesn’t correctly set the required headers. These are necessary in order to make OctoPrint generate correct external URLs so that AJAX requests and download URLs work, and so that client IPs are read correctly.
`reverseProxy.prefixHeader`	`str`	The request header from which to determine the URL prefix under which OctoPrint is served by the reverse proxy.	`'X-Script-Name'`
`reverseProxy.schemeHeader`	`str`	The request header from which to determine the scheme (http or https) under which a specific request to OctoPrint was made to the reverse proxy.	`'X-Scheme'`
`reverseProxy.hostHeader`	`str`	The request header from which to determine the host under which OctoPrint is served by the reverse proxy.	`'X-Forwarded-Host'`
`reverseProxy.serverHeader`	`str`	The request header from which to determine the server name under which OctoPrint is served by the reverse proxy. Can also be read from the `hostHeader`.	unset
`reverseProxy.portHeader`	`str`	The request header from which to determine the post number under which OctoPrint is served by the reverse proxy. Can also be read from the `hostHeader`.	unset
`reverseProxy.prefixFallback`	`str`	Use this option to define an optional URL prefix (with a leading `/`, so absolute to your server’s root) under which to run OctoPrint. This should only be needed if you want to run OctoPrint behind a reverse proxy under a different root endpoint than `/` and can’t configure said reverse proxy to send a prefix HTTP header (`X-Script-Name` by default, see above) with forwarded requests.	unset
`reverseProxy.schemeFallback`	`str`	Use this option to define an optional forced scheme (http or https) under which to run OctoPrint. This should only be needed if you want to run OctoPrint behind a reverse proxy that also does HTTPS termination but can’t configure said reverse proxy to send a scheme HTTP header (`X-Scheme` by default, see above) with forwarded requests.	unset
`reverseProxy.hostFallback`	`str`	Use this option to define an optional forced host under which to run OctoPrint. This should only be needed if you want to run OctoPrint behind a reverse proxy with a different hostname than OctoPrint itself but can’t configure said reverse proxy to send a host HTTP header (`X-Forwarded-Host` by default, see above) with forwarded requests.	unset
`reverseProxy.serverFallback`	`str`	Use this option to define an optional forced server name under which to run OctoPrint. This should only be needed if you want to run OctoPrint behind a reverse proxy with a different hostname than OctoPrint itself but can’t configure said reverse proxy to send a host HTTP Header (`X-Forwarded-Host` by default, see above) or a server HTTP Header as manually defined.	unset
`reverseProxy.portFallback`	`str`	Use this option to define an optional forced port under which to run OctoPrint. This should only be needed if you want to run OctoPrint behind a reverse proxy with a different hostname than OctoPrint itself but can’t configure said reverse proxy to send a host HTTP Header (`X-Forwarded-Host` by default, see above) or a port HTTP Header as manually defined.	unset
`reverseProxy.trustedProxies`	`list[str]`	List of trusted proxy servers for which to ignore the IP address when trying to determine the connecting client’s IP address. A reverse proxy on the same machine as OctoPrint (e.g. as found on OctoPi) will be handled correctly by default through `trustLocalhostProxies`, further proxies in front of that you’ll have to add yourself here.	`[]`
`reverseProxy.trustLocalhostProxies`	`bool`	Whether to trust the local machine to act as a reverse proxy. Defaults to true, will ensure that `127.0.0.0/8` and `::1` will always be considered to be included in `trustedProxies`. If you want to explicitly disable trusting the local machine, set this to `false` and don’t include the local machine in trustedProxies (as in, don’t include `127.0.0.1`, `127.0.0.0/8` or `::1`).	`True`
`uploads.*`		Settings for file uploads to OctoPrint, such as maximum allowed file size and header suffixes to use for streaming uploads. OctoPrint does some nifty things internally in order to allow streaming of large file uploads to the application rather than just storing them in memory. For that it needs to do some rewriting of the incoming upload HTTP requests, storing the uploaded file to a temporary location on disk and then sending an internal request to the application containing the original filename and the location of the temporary file.
`uploads.maxSize`	`int`	Maximum size of uploaded files in bytes, defaults to 1GB.	`1073741824`
`uploads.nameSuffix`	`str`	Suffix used for storing the filename in the file upload headers when streaming uploads.	`'name'`
`uploads.pathSuffix`	`str`	Suffix used for storing the path to the temporary file in the file upload headers when streaming uploads.	`'path'`
`maxSize`	`int`	Maximum size of requests other than file uploads in bytes, defaults to 100KB.	`102400`
`commands.*`		Commands to restart/shutdown octoprint or the system it’s running on.
`commands.systemShutdownCommand`	`str`	Command to shut down the system OctoPrint is running on.	unset
`commands.systemRestartCommand`	`str`	Command to restart the system OctoPrint is running on.	unset
`commands.serverRestartCommand`	`str`	Command to restart OctoPrint.	unset
`commands.localPipCommand`	`str`	`pip` command associated with OctoPrint, used for installing plugins and updates, if unset (default) the command will be autodetected based on the current python executable. Unless you have a really special setup this is the right way to do it and there should be no need to ever touch this setting.	unset
`onlineCheck.*`		Configuration of the regular online connectivity check.
`onlineCheck.enabled`	`bool`	Whether the online check is enabled. Ships unset, the user will be asked to make a decision as part of the setup wizard.	unset
`onlineCheck.interval`	`int`	Interval in which to check for online connectivity (in seconds), defaults to 15 minutes.	`900`
`onlineCheck.host`	`str`	DNS host against which to check, defaults to Cloudflare’s DNS.	`'1.1.1.1'`
`onlineCheck.port`	`int`	DNS port against which to check, defaults to the standard DNS port.	`53`
`onlineCheck.name`	`str`	Host name for which to check name resolution, defaults to OctoPrint’s main domain.	`'octoprint.org'`
`pluginBlacklist.*`		Configuration of the plugin blacklist.
`pluginBlacklist.enabled`	`bool`	Whether use of the blacklist is enabled. If unset, the user will be asked to make a decision as part of the setup wizard.	unset
`pluginBlacklist.url`	`str`	The URL from which to fetch the blacklist.	`'https://plugins.octoprint.org/blacklist.json'`
`pluginBlacklist.ttl`	`int`	Time to live of the cached blacklist, in seconds (default: 15 minutes).	`900`
`pluginBlacklist.timeout`	`float`	Timeout for fetching the blacklist, in seconds (default: 3.05 seconds).	`3.05`
`pythonEolCheck.*`		Configuration of the Python EOL warning.
`pythonEolCheck.enabled`	`bool`	Whether to enable the Python EOL warning.	`True`
`pythonEolCheck.url`	`str`	URL to fetch the Python EOL data from.	`'https://get.octoprint.org/python-eol'`
`pythonEolCheck.ttl`	`int`	Time to live of the cached Python EOL data, in minutes (default: 24 hours).	`1440`
`pythonEolCheck.fallback`	`dict[str, octoprint.schema.config.server.PythonEolEntry]`	Fallback data for Python EOL data, in case the online check fails.	`{'3.7': {'date': '2023-06-27', 'last_octoprint': '1.11.*'}, '3.8': {'date': '2024-10-31'}}`
`diskspace.*`		Settings of when to display what disk space warning.
`diskspace.warning`	`int`	Threshold (bytes) after which to consider disk space becoming sparse, defaults to 500MB.	`524288000`
`diskspace.critical`	`int`	Threshold (bytes) after which to consider disk space becoming critical, defaults to 200MB.	`209715200`
`preemptiveCache.*`		Configuration of the preemptive cache.
`preemptiveCache.exceptions`	`list[str]`	Which server paths to exclude from the preemptive cache, e.g. `/some/path`.	`[]`
`preemptiveCache.until`	`int`	How many days to leave unused entries in the preemptive cache config.	`7`
`ipCheck.*`		Configuration of the client IP check to warn about connections from external networks.
`ipCheck.enabled`	`bool`	Whether to enable the check.	`True`
`ipCheck.trustedSubnets`	`list[str]`	Additional non-local subnets to consider trusted, in CIDR notation, e.g. `192.168.1.0/24`.	`[]`
`allowFraming`	`bool`	Whether to allow OctoPrint to be embedded in a frame or not. Note that depending on your setup you might have to set SameSite to None, Secure to true and serve OctoPrint through a reverse proxy that enables https for cookies and thus logging in to work.	`False`
`cookies.*`		Settings for further configuration of the cookies that OctoPrint sets (login, remember me, …).
`cookies.secure`	`bool`	Whether to set the `Secure` flag to true on cookies. Only set to true if you are running OctoPrint behind a reverse proxy taking care of SSL termination.	`False`
`cookies.samesite`	`str`	`SameSite` setting to use on the cookies. Defaults to `Lax`. Be advised that if forced unset, this has security implications as many browsers now default to `Lax` unless you configure cookies to be set with the `Secure` flag, explicitly set the `SameSite` setting here and also serve OctoPrint over https. The `Lax` setting is known to cause issues with embedding OctoPrint in frames. See also Cookies default to SameSite=Lax, Reject insecure SameSite=None cookies and issue #3482.	`'Lax'`
`allowedLoginRedirectPaths`	`list[str]`	List of paths that are allowed to be used as redirect targets for the login page, in addition to the default ones (`/`, `/recovery/` and `/plugin/appkeys/auth/`).	`[]`

Python EOL Check fallback data

Name	Type	Description	Default
`date`	`str`	The date when the Python version will reach EOL, in format YYYY-MM-DD.	required
`last_octoprint`	`str`	The last OctoPrint version that will support this Python version, optional.	unset

Notes¶

Note

If you want to run OctoPrint behind a reverse proxy such as HAProxy or Nginx and use a different base URL than the server root / you have two options to achieve this. One approach is using the configuration settings baseUrl and scheme mentioned above in which OctoPrint will only work under the configured base URL.

The second and better approach is to make your proxy send a couple of custom headers with each forwarded requests:

X-Script-Name: should contain your custom baseUrl (absolute server path), e.g. /octoprint
X-Scheme: should contain your custom URL scheme to use (if different from http), e.g. https

If you use these headers OctoPrint will work both via the reverse proxy as well as when called directly. Take a look into OctoPrint’s wiki for some examples on how to configure this.

Note

If you want to embed OctoPrint in a frame, you’ll need to set allowFraming to true or your browser will prevent this.

In future browser builds you will also have to make sure you frame is on the same domain as OctoPrint or that OctoPrint is served via https through a reverse proxy and has set cookies.secure to true or your browser will refuse to persist cookies and logging in will not work.

See also Cookies default to SameSite=Lax and Reject insecure SameSite=None cookies as well as this ticket on why OctoPrint cannot solve this on its own/ship with https that doesn’t cause scary warnings in your browser.

Slicing¶

Settings for the built-in slicing support.

Defaults¶

slicing:
  defaultProfiles: {}
  defaultSlicer: null
  enabled: true

Data model¶

Name	Type	Description	Default
`enabled`	`bool`	Whether to enable slicing support or not.	`True`
`defaultSlicer`	`str`	Default slicer to use.	unset
`defaultProfiles`	`dict[str, str]`	Default slicing profiles per slicer, maps slicer identifier to profile identifier.	`{}`

System¶

Use the following settings to add custom system commands to the “System” dropdown within OctoPrint’s top bar.

Defaults¶

system:
  actions: []

Data model¶

Name	Type	Description	Default
`actions[]`		A list of system actions to show in the UI.
`actions[].action`	`str`	The identifier used internally to identify the action. Set to `divider` to generate a divider in the menu.	required
`actions[].name`	`str`	The name of the action that will be shown on the menu. Must be set if the action is not a divider.	unset
`actions[].command`	`str`	The command to execute when the action is selected. Must be set if the action is not a divider.	unset
`actions[].async`	`bool`	Whether to run the command asynchronously.	`False`
`actions[].confirm`	`str`	An optional confirmation message to show before executing the command.	unset
`actions[].fresh_credentials`	`bool`	Whether to require a fresh credential check for executing the command.	`False`

Actions consist of a name shown to the user, an action identifier used by the code and the actual command including any argument needed for its execution. By default OctoPrint blocks until the command has returned so that the exit code can be used to show a success or failure message; use the flag async: true for commands that don’t return.

Optionally you can add a confirmation message to display before actually executing the command (should be set to False if a confirmation dialog is not desired).

Name	Type	Description	Default
`action`	`str`	The identifier used internally to identify the action. Set to `divider` to generate a divider in the menu.	required
`name`	`str`	The name of the action that will be shown on the menu. Must be set if the action is not a divider.	unset
`command`	`str`	The command to execute when the action is selected. Must be set if the action is not a divider.	unset
`async`	`bool`	Whether to run the command asynchronously.	`False`
`confirm`	`str`	An optional confirmation message to show before executing the command.	unset
`fresh_credentials`	`bool`	Whether to require a fresh credential check for executing the command.	`False`

Example¶

The following example defines a command for shutting down the system under Linux. It assumes that the user under which OctoPrint is running is allowed to do this without password entry:

system:
  actions:
  - name: Shutdown
    action: shutdown
    command: sudo shutdown -h now
    confirm: You are about to shutdown the system.

You can also add a divider by setting action to divider like this:

system:
  actions:
  - action: divider

Temperature¶

Use the following settings to configure temperature profiles which will be displayed in the temperature tab.

Defaults¶

temperature:
  cutoff: 30
  profiles:
  - bed: 100
    extruder: 210
    name: ABS
  - bed: 60
    extruder: 180
    name: PLA
  sendAutomatically: false
  sendAutomaticallyAfter: 1

Data model¶

Name	Type	Description	Default
`profiles[]`		Temperature profiles to offer in the UI for quick pre-heating.
`profiles[].name`	`str`	Name of the profile.	required
`profiles[].extruder`	`int`	Hotend temperature to set with the profile.	required
`profiles[].bed`	`int`	Bed temperature to set with the profile.	required
`cutoff`	`int`	Cut off time for the temperature data, in minutes.	`30`
`sendAutomatically`	`bool`	Whether to send new temperature settings made in the UI automatically.	`False`
`sendAutomaticallyAfter`	`int`	After what time to send the new temperature settings automatically, in seconds.	`1`

The individual temperature profiles are defined like this:

Name	Type	Description	Default
`name`	`str`	Name of the profile.	required
`extruder`	`int`	Hotend temperature to set with the profile.	required
`bed`	`int`	Bed temperature to set with the profile.	required

Terminal Filters¶

Use the following settings to define a set of terminal filters to display in the terminal tab for filtering certain lines from the display terminal log.

Defaults¶

terminalFilters:
- name: Suppress temperature messages
  regex: '(Send: (N\d+\s+)?M105)|(Recv:\s+(ok\s+([PBN]\d+\s+)*)?([BCLPR]|T\d*):-?\d+)'
- name: Suppress SD status messages
  regex: '(Send: (N\d+\s+)?M27)|(Recv: SD printing byte)|(Recv: Not SD printing)'
- name: Suppress position messages
  regex: (Send:\s+(N\d+\s+)?M114)|(Recv:\s+(ok\s+)?X:[+-]?([0-9]*[.])?[0-9]+\s+Y:[+-]?([0-9]*[.])?[0-9]+\s+Z:[+-]?([0-9]*[.])?[0-9]+\s+E\d*:[+-]?([0-9]*[.])?[0-9]+).*
- name: Suppress wait responses
  regex: 'Recv: wait'
- name: Suppress processing responses
  regex: 'Recv: (echo:\s*)?busy:\s*processing'

Data model¶

Each filter entry in the list is a dictionary with the following keys:

Name	Type	Description	Default
`name`	`str`	The name of the filter.	required
`regex`	`str`	The regular expression to match. Use JavaScript regular expressions.	required

Webcam¶

Use the following settings to configure webcam support:

webcam:
  bitrate: 10000k
  cleanTmpAfterDays: 7
  defaultWebcam: classic
  ffmpeg: null
  ffmpegCommandline: '{ffmpeg} -framerate {fps} -i "{input}" -vcodec {videocodec}
    -threads {threads} -b:v {bitrate} -f {containerformat} -y {filters} "{output}"'
  ffmpegThreads: 1
  ffmpegThumbnailCommandline: '{ffmpeg} -sseof -1 -i "{input}" -update 1 -q:v 0.7
    "{output}"'
  ffmpegVideoCodec: libx264
  renderAfterPrintDelay: 0
  snapshotWebcam: classic
  timelapse:
    fps: 25
    options:
      capturePostRoll: null
      interval: null
      retractionZHop: null
    postRoll: 0
    renderAfterPrint: always
    type: 'off'
  timelapseEnabled: true
  watermark: true
  webcamEnabled: true

Name	Type	Description	Default
`webcamEnabled`	`bool`	Use this option to enable display of a webcam stream in the UI, e.g. via MJPG-Streamer. Webcam support will be disabled if not set.	`True`
`timelapseEnabled`	`bool`	Use this option to enable timelapse support via snapshot, e.g. via MJPG-Streamer. Timelapse support will be disabled if not set.	`True`
`ffmpeg`	`str`	Path to ffmpeg binary to use for creating timelapse recordings. Timelapse support will be disabled if not set.	unset
`ffmpegThreads`	`int`	Number of how many threads to instruct ffmpeg to use for encoding.	`1`
`ffmpegVideoCodec`	`str`	Videocodec to be used for encoding.	`'libx264'`
`bitrate`	`str`	The bitrate to use for rendering the timelapse video. This gets directly passed to ffmpeg.	`'10000k'`
`watermark`	`bool`	Whether to include a “created with OctoPrint” watermark in the generated timelapse recordings.	`True`
`ffmpegCommandline`	`str`	The full commandline to use for rendering timelapse recordings through ffmpeg. Supports the following placeholders: `ffmpeg`: the ffmpeg command as defined under `webcam.ffmpeg` `fps`: the fps setting as defined by the timelapse configuration `input`: the path to the input files `videocodec`: the video codec to use, as defined in `webcam.ffmpegVideoCodec` `threads`: the number of threads to use, as defined in `webcam.ffmpegThreads` `bitrate`: the bitrate to use, as defined in `webcam.bitrate` `containerformat`: the container format to use, based on the selected codec `filters`: the filter chain `output`: the path to the output file	`'{ffmpeg} -framerate {fps} -i "{input}" -vcodec {videocodec} -threads {threads} -b:v {bitrate} -f {containerformat} -y {filters} "{output}"'`
`ffmpegThumbnailCommandline`	`str`	The full commandline to use for generating thumbnails through ffmpeg. Supports the following placeholders: `ffmpeg`: the ffmpeg command as defined under `webcam.ffmpeg` `input`: the path to the input file `output`: the path to the output file	`'{ffmpeg} -sseof -1 -i "{input}" -update 1 -q:v 0.7 "{output}"'`
`timelapse.*`		The default timelapse settings.
`timelapse.type`	`str`	The timelapse type. Valid values: `off`, `timed`, `zchange`.	`'off'`
`timelapse.fps`	`int`	The framerate at which to render the movie.	`25`
`timelapse.postRoll`	`int`	The number of seconds in the rendered video to add after a finished print. The exact way how the additional images will be recorded depends on timelapse type. `zchange` timelapses will take one final picture and add it `fps * postRoll` times. `timed` timelapses continue to record just like at the beginning, so the recording will continue another `fps * postRoll * interval` seconds. This behaviour can be overridden by setting the `capturePostRoll` option to `false`, in which case the post roll will be created identically to `zchange` mode.	`0`
`timelapse.renderAfterPrint`	`str`	Determines whether rendering the timelapse should be done automatically after the print is finished. This can be done always, only after successful prints, only after failed prints, or never. Valid values: `always`, `failure`, `off`, `success`.	`'always'`
`timelapse.options.*`		Additional options depending on the timelapse type.
`timelapse.options.interval`	`int`	`timed` timelapses only: The interval which to leave between images in seconds.	unset
`timelapse.options.capturePostRoll`	`bool`	`timed` timelapses only: Whether to capture the snapshots for the post roll (`true`) or just copy the last captured snapshot from the print over and over again (`false`).	unset
`timelapse.options.retractionZHop`	`float`	`zchange` timelapses only: z-hop height during retractions to ignore for capturing snapshots.	unset
`cleanTmpAfterDays`	`int`	After how many days unrendered timelapses will be deleted.	`7`
`renderAfterPrintDelay`	`int`	Delay to wait for after print end before rendering timelapse, in seconds. If another print gets started during this time, the rendering will be postponed.	`0`
`defaultWebcam`	`str`	The name of the default webcam	`'classic'`
`snapshotWebcam`	`str`	The name of the default webcam to use for snapshots	`'classic'`