> For the complete documentation index, see [llms.txt](https://www.opal-rt.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://www.opal-rt.com/docs/hypersim/model-and-simulation/edit-a-model-schematic/import-and-export-a-project.md).

# Import & Export a Project

The **project import** and the **project export** features are available through the **Project** command on HYPERSIM ribbon.

## Portability guidelines <a href="#portability-guidelines" id="portability-guidelines"></a>

Most HYPERSIM features that interact with the file system allow files to be stored anywhere accessible from the host computer. While this flexibility can simplify development, it can also make models more difficult to transfer, share, and maintain.

To improve portability and reduce configuration issues, it is recommended to create a dedicated parent folder for each HYPERSIM model and store all related files within that directory.

* **For projects that require external configuration files** (such as **.pun**, **.dat**, **.edd**, and similar files), it is recommended to place these files in the same directory as the **.ecf** project file. Their paths can then be specified relative to the project location.

Whenever possible, HYPERSIM converts file paths to a **relative path** format. This allows projects to be copied, exported, or imported on another computer without requiring path updates. The following relative path formats are supported:

| Keyword             | Description                                                          | Example                                   |
| ------------------- | -------------------------------------------------------------------- | ----------------------------------------- |
| `%{USER_HOME}`      | Home directory of the user                                           | `C:\Users\JohnSmith`                      |
| `%{HYPERSIM_DIR}`   | HYPERSIM installation directory                                      | `C:\OPAL-RT\HYPERSIM\version`             |
| `%{TMP_DIR}`        | HyWorks JVM property `java.io.tmpdir`, usually equivalent to `%TMP%` | `%APPDATA%\Local\Temp`                    |
| `%{CIRCUIT_FOLDER}` | Parent folder of the ECF file                                        | `%{USER_HOME}\My_HYPERSIM_Models\Model_1` |
| `%{HYP_FOLDER}`     | Data folder associated with an ECF file                              | `%{CIRCUIT_FOLDER}\Model_1_hyp`           |

## Export a project <a href="#exporting-a-project" id="exporting-a-project"></a>

The **Export Wizard** helps users select the files required to run a project and add descriptive information before exporting them.

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-97b4a8565d76c66248877803902e89243723f33c%2Fexport-project-wizard.png?alt=media" alt=""><figcaption></figcaption></figure>

Some files are detected as necessary for the project. The description of these files is fixed, and they cannot be removed from the list.

{% columns %}
{% column %}
**Files currently auto-detected:**

* The ecf file
* The hyp folder
* Any file related to a UCM
* Any file related to a device
* The bitstream of an OpalBoards I/O interface
  {% endcolumn %}

{% column %}
**Additional files may need to be added manually, such as :**

* CID files
* ScopeView templates and references
* Sensor configuration files
  {% endcolumn %}
  {% endcolumns %}

The table includes a tooltip that explains the formatting used in the **File Path** column. Hover over the column entries to view additional information.

Click **Refresh** to rescan the project for required files and update the status of files already listed. For large models, this operation may take some time because each device is queried individually.

Use **Add Files** or **Add Folder** to include files that are not automatically detected. When a folder is added, all of its contents are packaged into the export archive.

The **Select All** toggle allows you to quickly select or clear all manually added files.

The wizard configuration is saved when the window is closed. If you export the project again in a later session, previously selected files and descriptions are restored automatically.

Once the export configuration is complete, click **Export** to create a ZIP archive containing all selected files and save it to the chosen destination.

### Zip output structure <a href="#zip-output-structure" id="zip-output-structure"></a>

Once the project has been successfully exported, a ZIP archive is created containing all selected project files. In the example above, the original folder structure is preserved within the archive.

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-cb59965687da46b8b11ff8609f86c3ee20632237%2Fexport-project-zip-content.png?alt=media" alt="" width="563"><figcaption></figcaption></figure>

The archive may also include the following additional items:

1. **ExceptionFiles** folder: If the project contains files located outside the project directory hierarchy, an **ExceptionFiles** folder is created. Any file or folder identified as being outside the project path is copied into this folder and included in the archive.
2. **README** file: A **README** text file is automatically generated and includes the descriptions entered in the export table. It also contains export metadata, such as the export date, author, and HYPERSIM version, as well as the original locations of the archived files. This information can be useful if the project needs to be reconstructed manually.

## Importing a Project <a href="#importing-a-project" id="importing-a-project"></a>

To import a project:

1. Select the ZIP archive containing the project.
2. Choose the destination folder where the project files will be extracted.

HYPERSIM then extracts the archive and automatically opens the project. If the archive contains external files, HYPERSIM will prompt you to open the **README** file in your default text editor. The README contains useful information about the exported project, including file descriptions and the original locations of any external files.

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-8c9468168cdef7b307773710f24c064e949c5489%2Fimport-project-dialog-box.png?alt=media" alt="" width="272"><figcaption></figcaption></figure>

Two approaches can help resolve issues in projects that depend on external files:

1. Move the files from the **ExceptionFiles** folder back to their original locations. This approach works only if the original paths are valid and do not depend on user-specific directories.
2. Move the files to a location within the project directory structure and update the circuit configuration to reference the new paths. Although this requires additional effort, it improves project portability and helps ensure that future exports include all required files automatically.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://www.opal-rt.com/docs/hypersim/model-and-simulation/edit-a-model-schematic/import-and-export-a-project.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
