Managing Katana projects in Multi-Platform Environments

When sharing Katana projects across different machines, it is sometimes necessary to adjust the format of file paths for different operating systems or to account for different folder structures.

To make a Katana project portable across multiple platforms, file paths should be set up so they are relative and not dependent on a system-specific folder structure. There are three ways to do this:

Using parameter expressions

Using an environment variable

Relative file paths without using an expression

Using Parameter Expressions

Python Expressions

Relative file paths can be set up by using Python parameter expressions. For example, right-click on a filename parameter, choose 'Expression' as the Value Mode and enter an expression:

project.dir + '/textures/testFile.png'

project.dir will then be resolved to the directory of the Katana project file. This is also valid:

path.join(project.dir, ‘/textures/testFile.png’)

Tip:  See the Katana Developer Guide for more information on Python expressions.

Reference Expressions

A reference expression is a form of parameter expression that can be evaluated without the overhead of a Python interpreter.

As of Katana 3.6, parameter reference expressions support concatenation using the + operator. For example:

=^/ + '_regionExtra'

Tip:  See the Katana Developer Guide for more information on reference expressions.

Using an Environment Variable

Alternatively, you can set an environment variable to point to the system specific root folder. To evaluate the variable in your parameter, there are two options:

Use a parameter expression. For example:

getenv("OS_PATH", tmpDir) + '/example/file/path'

Some nodes like Alembic_In also support the use of environment variables in a constant value for a file path parameter. For example:


Note:  This is not supported for every node type, in this case please use the first option of evaluating the environment variable via an expression.

Using a Relative File Path Without Using an Expression

Another option is to make use of relative file paths without using an expression. In this case you should specify your file paths relative to the project directory.

If you are launching Katana from the command line or use a bash or batch script, you can use the cd command to change the working directory for the environment you are launching Katana in.

For example, if your project is located here:


and you want to write relative path references to files located here:


you should set your working directory to the location of your Katana project file using the cd command:

cd C:/Users/username/Documents/Katana/Projects

Now you can write file paths relative to your working directory:


If your current working directory is specified incorrectly, the texture file paths cannot be resolved.

For example, setting your working directory to:

cd C:/Users/username/Documents/Katana

resolves the texture file relative to:


Tip:  If you are launching Katana from a command line, you can type the first few characters of a directory or file name, then press Tab to autocomplete the file or directory path. This may help to ensure your working directory is set correctly.
You can also use the dir (Windows) or ls (Linux) commands to list all files and directories in the current or specified directory.

If you are using a Python script to launch Katana, set the root using the Python os.chdir command similar to the following:

import os
from os.path import expanduser

project_directory = 'Projects'

os.chdir(os.path.join(expanduser('~'), 'Documents', 'Katana', project_directory))

The working directory is now set to:


Article:  For more information on how to set up a launcher script:
Q100242: Creating a Katana launcher script for Windows
Q100272: Creating a Katana launcher script for Linux