Load application resources from a known path.

Loading resources by specifying relative paths to filenames is often problematic in Python, as the working directory is not necessarily the same directory as the application’s script files.

This module allows applications to specify a search path for resources. Relative paths are taken to be relative to the application’s __main__ module. ZIP files can appear on the path; they will be searched inside. The resource module also behaves as expected when applications are bundled using py2exe or py2app.

As well as providing file references (with the file function), the resource module also contains convenience functions for loading images, textures, fonts, media and documents.

3rd party modules or packages not bound to a specific application should construct their own Loader instance and override the path to use the resources in the module’s directory.

Path format

The resource path path (see also Loader.__init__ and Loader.path) is a list of locations to search for resources. Locations are searched in the order given in the path. If a location is not valid (for example, if the directory does not exist), it is skipped.

Locations in the path beginning with an ampersand (‘’@’’ symbol) specify Python packages. Other locations specify a ZIP archive or directory on the filesystem. Locations that are not absolute are assumed to be relative to the script home. Some examples:

# Search just the `res` directory, assumed to be located alongside the
# main script file.
path = ['res']

# Search the directory containing the module `levels.level1`, followed
# by the `res/images` directory.
path = ['@levels.level1', 'res/images']

Paths are always case-sensitive and forward slashes are always used as path separators, even in cases when the filesystem or platform does not do this. This avoids a common programmer error when porting applications between platforms.

The default path is ['.']. If you modify the path, you must call reindex.


Since pyglet 1.1


FileLocation Location on the filesystem.
Loader Load program resource files from disk.
Location Abstract resource location.
URLLocation Location on the network.
ZIPLocation Location within a ZIP file.


ResourceNotFoundException(name) The named resource was not found on the search path.


add_font(self, name) Add a font resource to the application.
animation(self, name[, flip_x, flip_y, rotate]) Load an animation with optional transformation.
attributed(self, name) Load an attributed text document.
file(self, name[, mode]) Load a resource.
get_cached_animation_names(self) Get a list of animation filenames that have been cached.
get_cached_image_names(self) Get a list of image filenames that have been cached.
get_cached_texture_names(self) Get the names of textures currently cached.
get_script_home() Get the directory containing the program entry module.
get_settings_path(name) Get a directory to save user preferences.
get_texture_bins(self) Get a list of texture bins in use.
html(self, name) Load an HTML document.
image(self, name[, flip_x, flip_y, rotate, ...]) Load an image with optional transformation.
location(self, name) Get the location of a resource.
media(self, name[, streaming]) Load a sound or video resource.
reindex(self) Refresh the file index.
text(self, name) Load a plain text document.
texture(self, name) Load a texture.


path = ['.']

Default resource search path.

Locations in the search path are searched in order and are always case-sensitive. After changing the path you must call reindex.

See the module documentation for details on the path format.

Type:list of str



  • os
  • pyglet
  • sys
  • weakref
  • zipfile

Table Of Contents

Previous topic

load Function

Next topic

FileLocation Class