> For the complete documentation index, see [llms.txt](https://docs.sdv.dev/sdv/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sdv.dev/sdv/integration/local/excel.md).

# Excel

### Installation <a href="#bigqueryconnector" id="bigqueryconnector"></a>

To work with Excel files in SDV, please install SDV with the optional dependencies using:

```
pip install 'sdv[excel]'
```

### ExcelHandler <a href="#bigqueryconnector" id="bigqueryconnector"></a>

Use this object to create a handler for reading and writing an local Excel spreadsheet

```python
from sdv.io.local import ExcelHandler

connector = ExcelHandler()
```

**Parameters** (None)

**Output** An ExcelHandler object you can use to read and write an Excel spreadsheet

### read

Use this function to read an Excel spreadsheet from your local machine

```python
data = connector.read(
    filepath='project/data.xlsx',
    sheet_names=['guests', 'hotels']
)
```

**Parameters**

* (required) `filepath`: A string name of the Excel spreadsheet, which must end in `.xlsx`
* `sheet_names` : A list of sheet names to read from the overall spreadsheet. Each sheet is a tab in your spreadsheet file, and represents a different table.
  * (default) `None`: Read all the sheets of the overall spreadsheet
  * \<list>: Read only the sheets listed from the overall spreadsheet

**Output** A dictionary that contains all the data found the Excel file. The key is the name of the sheet and the value is a [pandas DataFrame](https://pandas.pydata.org/docs/reference/api/pandas.DataFrame.html) containing the data.

### write

Use this function to write synthetic data into an Excel spreadsheet

```python
connector.write(
  synthetic_data,
  filepath='project/synthetic_data.xlsx',
  mode='x'
)
```

**Parameters**

* (required) `synthetic_data`: You data, represented as a dictionary. The key is the name of each table and the value is a [pandas DataFrame](https://pandas.pydata.org/docs/reference/api/pandas.DataFrame.html) containing the data.&#x20;
* (required) `filepath`: A string name of the file where you would like to write the synthetic data
* `sheet_name_suffix`: The suffix to add to each sheet name. Use this if to add specific version numbers or other info.
  * (default) `None`: Do not add a suffix. Each sheet will be named with table name
  * \<string>: Append the suffix after each table name. Eg. a suffix `'_synth1'` will write a sheet as `table_synth1`&#x20;
* `mode`: A string signaling which mode of writing to use
  * (default) `'w'`: Write sheets to a new Excel file, clearing any existing file that may exist
  * `'a'`: Write the data as new sheets within an existing Excel file

**Output** (None) The data will be written as an Excel spreadsheet


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.sdv.dev/sdv/integration/local/excel.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.