# Can I Use Relative Paths in My OpenAI Plugin Configuration? A Complete Guide

> Yes you can use relative paths in your OpenAI plugin configuration. Learn how the system resolves paths relative to the plugin root for better portability.

- Repository: [OpenAI/plugins](https://github.com/openai/plugins)
- Tags: how-to-guide
- Published: 2026-07-05

---

**Yes, the OpenAI plugin system resolves file paths in [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) and [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json) relative to the plugin's root directory, using the `relativePath` helper function in [`plugins/plugin-eval/src/lib/files.js`](https://github.com/openai/plugins/blob/main/plugins/plugin-eval/src/lib/files.js) to ensure portability across environments.**

The `openai/plugins` repository demonstrates that all asset references—from icons to secondary configuration files—should use relative notation. Whether you are pointing to a logo asset or importing data within a skill script, relative paths ensure your plugin functions correctly regardless of where it is installed on the host filesystem.

## How Path Resolution Works in OpenAI Plugins

When the plugin loader encounters a file reference in your configuration, it computes the path relative to the plugin's installation directory. This prevents the brittleness of absolute system paths (like `/home/user/...`) that break when the plugin is deployed to different environments.

The resolution logic lives in [`plugins/plugin-eval/src/lib/files.js`](https://github.com/openai/plugins/blob/main/plugins/plugin-eval/src/lib/files.js). The `relativePath` function calculates the relative path between two locations, ensuring clean path formatting:

```javascript
// plugins/plugin-eval/src/lib/files.js
export function relativePath(fromPath, toPath) {
  const value = path.relative(fromPath, toPath) || ".";
  // …additional logic for home‑dir and cwd shortcuts…
  return value;
}

```

This utility guarantees that paths like `./assets/logo.png` are interpreted correctly against the plugin root, not the current working directory of the host process.

## Configuration Examples Using Relative Paths

### Referencing Static Assets in plugin.json

Asset paths for icons and logos must start with `./` to indicate they reside within the plugin folder. The `quartr` plugin demonstrates this pattern in [`plugins/quartr/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/quartr/.codex-plugin/plugin.json):

```json
{
  "name": "quartr",
  "version": "1.0.3",
  "description": "Public company IR data and earnings research",
  "interface": {
    "displayName": "Quartr",
    "composerIcon": "./assets/logo.png",
    "logo": "./assets/logo.png",
    "logoDark": "./assets/logo-dark.png"
  },
  "apps": "./.app.json"
}

```

In this manifest, `"composerIcon": "./assets/logo.png"` resolves to `{plugin_root}/assets/logo.png`. Similarly, `"apps": "./.app.json"` points to a secondary configuration file in the plugin's root directory.

### Accessing Files from Skill Scripts

Within skill scripts, you can resolve relative paths from the script's location using Node.js path utilities. This pattern works because the plugin loader maintains the relative structure of the source files:

```javascript
import path from "node:path";
import fs   from "node:fs";

/* Resolve a file that lives next to this script */
const dataPath = path.resolve(import.meta.url, "../data/sample.json");
const data = JSON.parse(fs.readFileSync(dataPath, "utf‑8"));
console.log(data);

```

Here, [`../data/sample.json`](https://github.com/openai/plugins/blob/main/../data/sample.json) navigates up one directory from the script's location to locate the data file, maintaining portability across different installation contexts.

## Best Practices for OpenAI Plugin Path Configuration

When authoring plugins in the `openai/plugins` ecosystem, follow these guidelines to ensure robust path resolution:

- **Always use the `./` prefix** for files in the plugin root or subdirectories, such as `"./assets/icon.png"`.
- **Avoid absolute paths** like `/Users/name/...` or `/opt/...` which fail when the plugin is copied to different systems.
- **Reference secondary configs relatively**: Point to [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json) using `"./.app.json"` rather than assuming file system structure.
- **Leverage the `relativePath` utility** if building custom tooling that processes plugin files, ensuring consistency with the core loader's behavior.

## Summary

- **Relative paths are fully supported** in OpenAI plugin configuration files, including [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) and [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json).
- **Resolution base**: All paths resolve against the plugin's root installation directory.
- **Key implementation**: The `relativePath` function in [`plugins/plugin-eval/src/lib/files.js`](https://github.com/openai/plugins/blob/main/plugins/plugin-eval/src/lib/files.js) handles the underlying path computation.
- **Best practice**: Use `./` or `../` prefixes for all file references to ensure cross-environment compatibility.

## Frequently Asked Questions

### Can I use absolute paths in my OpenAI plugin configuration?

No, you should avoid absolute paths. The OpenAI plugin system expects portable relative paths (starting with `./` or `../`) so that assets resolve correctly regardless of where the plugin is installed on the host filesystem. Absolute paths like `/home/user/plugins/...` will break when the plugin runs in different environments.

### What base directory are relative paths resolved against?

Relative paths in [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) and [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json) resolve against the **plugin's root directory**—the folder containing the configuration file. For example, `"./assets/logo.png"` in [`plugins/quartr/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/quartr/.codex-plugin/plugin.json) points to `plugins/quartr/.codex-plugin/assets/logo.png`.

### Are parent directory references (../) supported in plugin configurations?

Yes, parent directory references using `../` are supported, though less common for static assets. They resolve relative to the plugin root. Within skill scripts, `../` works as standard Node.js path resolution relative to the executing script's location.

### Does relative path resolution apply to both plugin.json and .app.json files?

Yes, the same resolution rules apply to both files. The `apps` field in [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) typically points to `"./.app.json"`, and all paths within [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json) are also resolved relative to the plugin's root directory using the same `relativePath` utility in [`plugins/plugin-eval/src/lib/files.js`](https://github.com/openai/plugins/blob/main/plugins/plugin-eval/src/lib/files.js).