[Files] section

This optional section defines any files Setup is to install on the user's system.

Here is an example of a [Files] section:

[Files]
Source: "CTL3DV2.DLL"; DestDir: "{sys}"; Flags: onlyifdoesntexist uninsneveruninstall
Source: "MYPROG.EXE"; DestDir: "{app}"
Source: "MYPROG.CHM"; DestDir: "{app}"
Source: "README.TXT"; DestDir: "{app}"; Flags: isreadme

See the Remarks section at the bottom of this topic for some important notes.

The following is a list of the supported parameters:

Source  (Required)

The name of the source file. The compiler will prepend the path of your installation's source directory if you do not specify a fully qualified pathname.

This can be a wildcard to specify a group of files in a single entry. When a wildcard is used, all files matching it use the same options.

When the flag external is specified, Source must be the full pathname of an existing file (or wildcard) on the distribution media or the user's system (e.g. "{src}\license.ini").

Constants may only be used when the external flag is specified, because the compiler does not do any constant translating itself.

Examples:
Source: "MYPROG.EXE"
Source: "Files\*"
DestDir  (Required)

The directory where the file is to be installed on the user's system. Will almost always begin with one of the directory constants. If the specified path does not already exist on the user's system, it will be created automatically, and removed automatically during uninstallation if empty.

Examples:
DestDir: "{app}"
DestDir: "{app}\subdir"
DestName

This parameter specifies a new name for the file when it is installed on the user's system. By default, Setup uses the name from the Source parameter, so in most cases it's not necessary to specify this parameter.

Example:
DestName: "MYPROG2.EXE"
Excludes

Specifies a list of patterns to exclude, separated by commas. This parameter cannot be combined with the external flag.

Patterns may include wildcard characters ("*" and "?"). Note that unlike the Source parameter, a simple Unix-style pattern matching routine is used for Excludes. Dots in the pattern are always significant, thus "*.*" will not exclude a file with no extension (instead, use just "*"). Also, question marks always match exactly one character, thus "?????" will not exclude files with names less than five characters long.

If a pattern starts with a backslash ("\") it is matched against the start of a path name, otherwise it is matched against the end of a path name. Thus "\foo" will only exclude a file named "foo" at the base of the tree. On the other hand, "foo" will exclude any file named "foo" anywhere in the tree.

The patterns may include backslashes. "foo\bar" will exclude both "foo\bar" and "subdir\foo\bar". "\foo\bar" will only exclude "foo\bar".

Examples:
Source: "*"; Excludes: "*.~*"
Source: "*"; Excludes: "*.~*,\Temp\*"; Flags: recursesubdirs
ExternalSize

This parameter must be combined with the external flag and specifies the size of the external file in bytes. If this parameter is not specified, Setup retrieves the file size at startup. Primarily useful for files that aren't available at startup, for example files located on a second disk when disk spanning is being used.

Example:
ExternalSize: 1048576; Flags: external
CopyMode

You should not use this parameter in any new scripts. This parameter was deprecated and replaced by flags in Inno Setup 3.0.5:

CopyMode: normal -> Flags: promptifolder
CopyMode: alwaysskipifsameorolder -> no flags
CopyMode: onlyifdoesntexist -> Flags: onlyifdoesntexist
CopyMode: alwaysoverwrite -> Flags: ignoreversion
CopyMode: dontcopy -> Flags: dontcopy

What was CopyMode: alwaysskipifsameorolder is now the default behavior. (The previous default was CopyMode: normal.)

Attribs

Specifies additional attributes for the file. This can include one or more of the following: readonly, hidden, system. If this parameter is not specified, Setup does not assign any special attributes to the file.

Example:
Attribs: hidden system
Permissions

Specifies additional permissions to grant in the file's ACL (access control list). It is not recommended that you use this parameter if you aren't familiar with ACLs or why you would need to change them, because misusing it could negatively impact system security.

For this parameter to have an effect the file must be located on a partition that supports ACLs (such as NTFS), and the current user must be able to change the permissions on the file. In the event these conditions are not met, no error message will be displayed, and the permissions will not be set.

This parameter should only be used on files private to your application. Never change the ACLs on shared system files, otherwise you can open up security holes on your users' systems.

The specified permissions are set regardless of whether the file existed prior to installation.

This parameter can include one or more space separated values in the format:

The following access types are supported for the [Files] section:

full

Grants "Full Control" permission, which is the same as modify (see below), but additionally allows the specified user/group to take ownership of the file and change its permissions. Use sparingly; generally, modify is sufficient.

modify

Grants "Modify" permission, which allows the specified user/group to read, execute, modify, and delete the file.

readexec

Grants "Read & Execute" permission, which allows the specified user/group to read and execute the file.

Example:
Permissions: users-modify
FontInstall

Tells Setup the file is a font that needs to be installed. The value of this parameter is the name of the font as stored in the registry or WIN.INI. This must be exactly the same name as you see when you double-click the font file in Explorer. Note that Setup will automatically append " (TrueType)" to the end of the name.

If the file is not a TrueType font, you must specify the flag fontisnttruetype in the Flags parameter.

It's recommended that you use the flags onlyifdoesntexist and uninsneveruninstall when installing fonts to the {fonts} directory.

To successfully install a font, the user must be a member of the Power Users or Administrators groups.

For compatibility with 64-bit Windows, fonts should not be installed to the {sys} directory. Use {fonts} as the destination directory instead.

Example:
Source: "OZHANDIN.TTF"; DestDir: "{fonts}"; FontInstall: "Oz Handicraft BT"; Flags: onlyifdoesntexist uninsneveruninstall
StrongAssemblyName

Specifies the strong assembly name of the file. Used by Uninstall only.

This parameter is ignored if the gacinstall flag isn't also specified.

Example:
StrongAssemblyName: "MyAssemblyName, Version=1.0.0.0, Culture=neutral, PublicKeyToken=abcdef123456, ProcessorArchitecture=MSIL"
Flags

This parameter is a set of extra options. Multiple options may be used by separating them by spaces. The following options are supported:

32bit

Causes the {sys} constant to map to the 32-bit System directory when used in the Source and DestDir parameters, the regserver and regtypelib flags to treat the file as 32-bit, and the sharedfile flag to update the 32-bit SharedDLLs registry key. This is the default behavior in a 32-bit mode install.

64bit

Causes the {sys} constant to map to the 64-bit System directory when used in the Source and DestDir parameters, the regserver and regtypelib flags to treat the file as 64-bit, and the sharedfile flag to update the 64-bit SharedDLLs registry key. This is the default behavior in a 64-bit mode install.

allowunsafefiles

Disables the compiler's automatic checking for unsafe files. It is strongly recommended that you DO NOT use this flag, unless you are absolutely sure you know what you're doing.

comparetimestamp

(Not recommended; see below)
Instructs Setup to proceed to comparing time stamps if the file being installed already exists on the user's system, and at least one of the following conditions is true:

  • Neither the existing file nor the file being installed has version info.
  • The ignoreversion flag is also used on the entry.
  • The replacesameversion flag isn't used, and the existing file and the file being installed have the same version number (as determined by the files' version info).

If the existing file has an older time stamp than the file being installed, the existing file will replaced. Otherwise, it will not be replaced.

Use of this flag is not recommended except as a last resort, because there is an inherent issue with it: NTFS partitions store time stamps in UTC (unlike FAT partitions), which causes local time stamps -- what Inno Setup works with by default -- to shift whenever a user changes their system's time zone or when daylight saving time goes into or out of effect. This can create a situation where files are replaced when the user doesn't expect them to be, or not replaced when the user expects them to be.

confirmoverwrite

Always ask the user to confirm before replacing an existing file.

createallsubdirs

By default the compiler skips empty directories when it recurses subdirectories searching for the Source filename/wildcard. This flag causes these directories to be created at install time (just like if you created [Dirs] entries for them).

Must be combined with recursesubdirs.

deleteafterinstall

Instructs Setup to install the file as usual, but then delete it once the installation is completed (or aborted). This can be useful for extracting temporary data needed by a program executed in the script's [Run] section.

This flag will not cause existing files that weren't replaced during installation to be deleted.

This flag cannot be combined with the isreadme, regserver, regtypelib, restartreplace, sharedfile, or uninsneveruninstall flags.

dontcopy

Don't copy the file to the user's system during the normal file copying stage but do statically compile the file into the installation. This flag is useful if the file is handled by the [Code] section exclusively and extracted using ExtractTemporaryFile.

dontverifychecksum

Prevents Setup from verifying the file checksum after extraction. Use this flag on files you wish to modify while already compiled into Setup.

Must be combined with nocompression.

external

This flag instructs Inno Setup not to statically compile the file specified by the Source parameter into the installation files, but instead copy from an existing file on the distribution media or the user's system. See the Source parameter description for more information.

fontisnttruetype

Specify this flag if the entry is installing a non-TrueType font with the FontInstall parameter.

gacinstall

Install the file into the .NET Global Assembly Cache. When used in combination with sharedfile, the file will only be uninstalled when the reference count reaches zero.

To uninstall the file Uninstaller uses the strong assembly name specified by parameter StrongAssemblyName.

An exception will be raised if an attempt is made to use this flag on a system with no .NET Framework present.

ignoreversion

Don't compare version info at all; replace existing files regardless of their version number.

This flag should only be used on files private to your application, never on shared system files.

isreadme

File is the "README" file. Only one file in an installation can have this flag. When a file has this flag, the user will asked if he/she would like to view the README file after the installation has completed. If Yes is chosen, Setup will open the file, using the default program for the file type. For this reason, the README file should always end with an extension like .txt, .wri, or .doc.

Note that if Setup has to restart the user's computer (as a result of installing a file with the flag restartreplace or if the AlwaysRestart [Setup] section directive is yes), the user will not be given an option to view the README file.

nocompression

Prevents the compiler from attempting to compress the file. Use this flag on file types that you know can't benefit from compression (for example, JPEG images) to speed up the compilation process and save a few bytes in the resulting installation.

noencryption

Prevents the file from being stored encrypted. Use this flag if you have enabled encryption (using the [Setup] section directive Encryption) but want to be able to extract the file using the [Code] section support function ExtractTemporaryFile before the user has entered the correct password.

noregerror

When combined with either the regserver or regtypelib flags, Setup will not display any error message if the registration fails.

onlyifdestfileexists

Only install the file if a file of the same name already exists on the user's system. This flag may be useful if your installation is a patch to an existing installation, and you don't want files to be installed that the user didn't already have.

onlyifdoesntexist

Only install the file if it doesn't already exist on the user's system.

overwritereadonly

Always overwrite a read-only file. Without this flag, Setup will ask the user if an existing read-only file should be overwritten.

promptifolder

By default, when a file being installed has an older version number (or older time stamp, when the comparetimestamp flag is used) than an existing file, Setup will not replace the existing file. (See the Remarks section at the bottom of this topic for more details.) When this flag is used, Setup will ask the user whether the file should be replaced, with the default answer being to keep the existing file.

recursesubdirs

Instructs the compiler or Setup to also search for the Source filename/wildcard in subdirectories under the Source directory.

regserver

Register the DLL/OCX file. With this flag set, Setup will call the DllRegisterServer function exported by the DLL/OCX file, and the uninstaller will call DllUnregisterServer prior to removing the file. When used in combination with sharedfile, the DLL/OCX file will only be unregistered when the reference count reaches zero.

On a 64-bit mode install, the file is assumed to be a 64-bit image and will be registered inside a 64-bit process. You can override this by specifying the 32bit flag.

See the Remarks at the bottom of this topic for more information.

regtypelib

Register the type library (.tlb). The uninstaller will unregister the type library (unless the flag uninsneveruninstall is specified). As with the regserver flag, when used in combination with sharedfile, the file will only be unregistered by the uninstaller when the reference count reaches zero.

On a 64-bit mode install running on an x64 edition of Windows, the type library will be registered inside a 64-bit process. You can override this by specifying the 32bit flag.

Registering type libraries in 64-bit mode on Itanium editions of Windows is not supported.

See the Remarks at the bottom of this topic for more information.

replacesameversion

When this flag is used and the file already exists on the user's system and it has the same version number as the file being installed, Setup will compare the files and replace the existing file if their contents differ.

The default behavior (i.e. when this flag isn't used) is to not replace an existing file with the same version number.

restartreplace

When an existing file needs to be replaced, and it is in use (locked) by another running process, Setup will by default display an error message. This flag tells Setup to instead register the file to be replaced the next time the system is restarted (by calling MoveFileEx or by creating an entry in WININIT.INI). When this happens, the user will be prompted to restart their computer at the end of the installation process.

NOTE: This flag has no effect if the user does not have administrative privileges. Therefore, when using this flag, it is recommended that you leave the PrivilegesRequired [Setup] section directive at the default setting of admin.

setntfscompression

Instructs Setup to enable NTFS compression on the file (even if it didn't replace the file). If it fails to set the compression state for any reason (for example, if compression is not supported by the file system), no error message will be displayed.

sharedfile

Specifies that the file is shared among multiple applications, and should only be removed at uninstall time if no other applications are using it. Most files installed to the Windows System directory should use this flag, including .OCX, .BPL, and .DPL files.

Windows' standard shared file reference-counting mechanism (located in the registry under HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\SharedDLLs) is used to keep track of how many applications depend on the file. Each time the file is installed, the reference count for the file is incremented. (This happens regardless of whether the installer actually replaces the file on disk.) When an application using the file is uninstalled, the reference count is decremented. If the count reaches zero, the file is deleted (with the user's confirmation, unless the uninsnosharedfileprompt flag is also specified).

If Setup is run more than once, the reference count for the file will be incremented more than once. The uninstaller will decrement the reference count the same number of times, however, so no references are leaked (provided the UninstallLogMode [Setup] section directive isn't changed from its default setting of append).

When this flag is used, do not specify {syswow64} in the DestDir parameter; use {sys} instead. Even though {sys} and {syswow64} map to the same underlying directory in a 32-bit mode install, the path name must exactly match what every other existing installer is using; otherwise, a second reference count for the file would be created, which could result in the file being removed prematurely. If you need to install a shared file to the 32-bit System directory in a 64-bit mode install, specify {sys} in the DestDir parameter and additionally include the 32bit flag.

skipifsourcedoesntexist

This flag instructs the compiler -- or Setup, if the external flag is also used -- to silently skip over the entry if the source file does not exist, instead of displaying an error message.

solidbreak

When solid compression is enabled, this flag instructs the compiler to finalize the current compression stream and begin a new one before compressing the file(s) matched by Source. This allows Setup to seek to the file instantly without having to decompress any preceding files first. May be useful in a large, multi-component installation if you find too much time is being spent decompressing files belonging to components that weren't selected.

sortfilesbyextension

This flag instructs the compiler to compress the found files sorted by extension before it sorts by path name. This potentially decreases the size of Setup if solid compression is also used.

sortfilesbyname

This flag instructs the compiler to compress the found files sorted by name before it sorts by path name. This potentially decreases the size of Setup if solid compression is also used. If sortfilesbyextension is also used, files are first sorted by extension.

touch

This flag causes Setup to set the time/date stamp of the installed file(s) to that which is specified by the TouchDate and TouchTime [Setup] section directives.

This flag has no effect if combined with the external flag.

uninsnosharedfileprompt

When uninstalling the shared file, automatically remove the file if its reference count reaches zero instead of asking the user. Must be combined with the sharedfile flag to have an effect.

uninsremovereadonly

When uninstalling the file, remove any read-only attribute from the file before attempting to delete it.

uninsrestartdelete

When this flag is used and the file is in use at uninstall time, the uninstaller will queue the file to be deleted when the system is restarted, and at the end of the uninstallation process ask the user if he/she wants to restart. This flag can be useful when uninstalling things like shell extensions which cannot be programmatically stopped. Note that administrative privileges are required for this flag to have an effect.

uninsneveruninstall

Never remove the file. This flag can be useful when installing very common shared files that shouldn't be deleted under any circumstances, such as MFC DLLs.

Note that if this flag is combined with the sharedfile flag, the file will never be deleted at uninstall time but the reference count will still be properly decremented.

unsetntfscompression

Instructs Setup to disable NTFS compression on the file (even if it didn't replace the file). If it fails to set the compression state for any reason (for example, if compression is not supported by the file system), no error message will be displayed.

Example:
Flags: isreadme

Components and Tasks Parameters

Common Parameters

Remarks

If a file already exists on the user's system, it by default will be replaced according to the following rules:

  1. If the existing file is an older version than the file being installed (as determined by the files' version info), the existing file will be replaced.
  2. If the existing file is the same version as the file being installed, the existing file will not be replaced, except if the replacesameversion flag is used and the content of the two files differs.
  3. If the existing file is a newer version than the file being installed, or if the existing file has version info but the file being installed does not, the existing file will not be replaced.
  4. If the existing file does not have version info, it will be replaced.

Certain flags such as onlyifdoesntexist, ignoreversion, and promptifolder alter the aforementioned rules.

If Setup is unable to replace an existing file because it is in use by another process, it will make up to 4 additional attempts to replace the file, delaying one second before each attempt. If all attempts fail, an error message will be displayed.

Setup registers all files with the regserver or regtypelib flags as the last step of installation. However, if the [Setup] section directive AlwaysRestart is yes, or if there are files with the restartreplace flag, all files get registered on the next reboot (by creating an entry in Windows' RunOnce registry key).

When files with a .HLP extension (Windows help files) are uninstalled, the corresponding .GID and .FTS files are automatically deleted as well. Similarly, when a .CHM (HTML Help) file is deleted, any .CHW (generated index) file is automatically deleted.