---
metadata:
  - name: generator
    content: Diplodoc Platform v5.50.6
alternate:
  - https://ytsaurus.tech/docs/en/api/python/start.md
  - https://ytsaurus.tech/docs/ru/api/python/start.md
---
> **Documentation Index:** Fetch the complete configuration index at https://ytsaurus.tech/docs/en/llms.txt

<!-- source: en/_includes/api/python/start.md -->
## Python API

{% note info "Note" %}

Before you start, install the Python client from the pip repository using the command:

```bash
pip install ytsaurus-client
```

{% endnote %}

What becomes available after installing the package:

- The Python yt library.
- The CLI binary [yt](https://ytsaurus.tech/docs/en/api/cli/cli.md).

Current package version requires **Python 3.8+**

### Installation { #install }

#### YSON libraries

To use the YSON format to work with tables, you need C++ bindings installed as a separate package. Installing [YSON bindings](https://ytsaurus.tech/docs/en/api/python/userdoc.md#yson_bindings):

```bash
pip install ytsaurus-yson
```

{% note warning "Attention!" %}

It is currently impossible to install YSON bindings on Windows.

{% endnote %}

{% note info "For Apple M1 platform users" %}

There are currently no YSON bindings built for the Apple platform. You can use [Rosetta 2](https://en.wikipedia.org/wiki/Rosetta_(software)) as a temporary solution and install the Python version for the x86_64 architecture.

Learn more [here](https://stackoverflow.com/questions/71691598/how-to-run-python-as-x86-with-rosetta2-on-arm-macos-machine).


{% endnote %}

To learn more about YSON, see [Formats](https://ytsaurus.tech/docs/en/api/python/userdoc.md#formats).

To find out the version of the installed Python wrapper, print the `yt.VERSION` variable or call the `yt --version` command.

If you encounter a problem, check the [FAQ](#faq) section. If the problem persists, write to the [chat](https://t.me/ytsaurus_ru).

[Library source code](https://github.com/ytsaurus/ytsaurus/tree/main/yt/python/yt/wrapper).

{% note warning "Attention!" %}

We do not recommend installing the library and its dependent packages in different ways at the same time. This can lead to problems that are difficult to diagnose.

{% endnote %}

#### Additional dependencies (extras) { #extras }

Some features require the additional dependencies that are not installed by default. They are declared in the extras sets of the `ytsaurus-client` package and are installed by specifying the set in square brackets:

| Set | Dependencies | Purpose |
| --- | --- | --- |
| `recommended` | `brotli`, `cryptography` | Recommended optional dependencies |
| `admin` | `kubernetes`, `docker` | [CLI admin commands](../../admin-guide/cli-admin.md) (`yt admin logs k8s`, `yt admin metrics replay`) |

```bash
pip install "ytsaurus-client[recommended]"
pip install "ytsaurus-client[admin]"
```

### User documentation { #userdoc }
* [General](https://ytsaurus.tech/docs/en/api/python/userdoc.md#common)
   - [Agreements used in the code](https://ytsaurus.tech/docs/en/api/python/userdoc.md#agreements)
   - [Client](https://ytsaurus.tech/docs/en/api/python/userdoc.md#client)
      - [Thread safety](https://ytsaurus.tech/docs/en/api/python/userdoc.md#threadsafety)
      - [Asynchronous client based on gevent](https://ytsaurus.tech/docs/en/api/python/userdoc.md#gevent)
   - [Configuration](https://ytsaurus.tech/docs/en/api/python/userdoc.md#configuration)
      - [Shared config](https://ytsaurus.tech/docs/en/api/python/userdoc.md#configuration_common)
      - [Logging setup](https://ytsaurus.tech/docs/en/api/python/userdoc.md#configuration_logging)
      - [Token setup](https://ytsaurus.tech/docs/en/api/python/userdoc.md#configuration_token)
      - [Setting up retries](https://ytsaurus.tech/docs/en/api/python/userdoc.md#configuration_retries)
   - [Errors](https://ytsaurus.tech/docs/en/api/python/userdoc.md#errors)
   - [Formats](https://ytsaurus.tech/docs/en/api/python/userdoc.md#formats)
   - [YPath](https://ytsaurus.tech/docs/en/api/python/userdoc.md#ypath)
* [Teams](https://ytsaurus.tech/docs/en/api/python/userdoc.md#commands)
   - [Working with Cypress](https://ytsaurus.tech/docs/en/api/python/userdoc.md#cypress_commands)
   - [Working with files](https://ytsaurus.tech/docs/en/api/python/userdoc.md#file_commands)
   - [Working with tables](https://ytsaurus.tech/docs/en/api/python/userdoc.md#table_commands)
      - [Data classes](https://ytsaurus.tech/docs/en/api/python/userdoc.md#dataclass)
      - [Schemas] { ../../../api/python/userdoc.md#table_schema }
      - [TablePath](https://ytsaurus.tech/docs/en/api/python/userdoc.md#tablepath_class)
      - [Teams](https://ytsaurus.tech/docs/en/api/python/userdoc.md#table_commands)
      - [Parallel table reading](https://ytsaurus.tech/docs/en/api/python/userdoc.md#parallel_read)
      - [Parallel table writing](https://ytsaurus.tech/docs/en/api/python/userdoc.md#parallel_write)
   - [Working with transactions and locks](https://ytsaurus.tech/docs/en/api/python/userdoc.md#transaction_commands)
   - [Running operations](https://ytsaurus.tech/docs/en/api/python/userdoc.md#run_operation_commands)
      - [SpecBuilder](https://ytsaurus.tech/docs/en/api/python/userdoc.md#spec_builder)
   - [Working with operations and jobs](https://ytsaurus.tech/docs/en/api/python/userdoc.md#operation_and_job_commands)
      - [Operation](https://ytsaurus.tech/docs/en/api/python/userdoc.md#operation_class)
      - [OperationsTracker](https://ytsaurus.tech/docs/en/api/python/userdoc.md#operations_tracker_class)
      - [OperationsTrackerPool](https://ytsaurus.tech/docs/en/api/python/userdoc.md#operations_tracker_pool_class)
   - [Working with access permissions](https://ytsaurus.tech/docs/en/api/python/userdoc.md#acl_commands)
   - [Working with dynamic tables](https://ytsaurus.tech/docs/en/api/python/userdoc.md#dyntables_commands)
   - [Other commands](https://ytsaurus.tech/docs/en/api/python/userdoc.md#etc_commands)
* [Python objects as operations](https://ytsaurus.tech/docs/en/api/python/userdoc.md#python_operations)
   - [General information](https://ytsaurus.tech/docs/en/api/python/userdoc.md#python_operations_intro)
   - [Preparing an operation from a job](https://ytsaurus.tech/docs/en/api/python/userdoc.md#prepare_operation)
   - [Decorators](https://ytsaurus.tech/docs/en/api/python/userdoc.md#python_decorators)
   - [Pickling functions and environments](https://ytsaurus.tech/docs/en/api/python/userdoc.md#pickling)
      - [Running Python workloads in open-source environments](https://ytsaurus.tech/docs/en/api/python/userdoc.md#python_open_source_environment)
      - [Running the local script inside Docker with `respawn_in_docker`](https://ytsaurus.tech/docs/en/api/python/userdoc.md#respawn_in_docker)
      - [General structure](https://ytsaurus.tech/docs/en/api/python/userdoc.md#pickling_description)
      - [Link to a post with tips](https://ytsaurus.tech/docs/en/api/python/userdoc.md#pickling_advises)
   - [Porto layers](https://ytsaurus.tech/docs/en/api/python/userdoc.md#porto_layers)
   - [tmpfs in jobs](https://ytsaurus.tech/docs/en/api/python/userdoc.md#tmpfs_in_jobs)
   - [Statistics in jobs](https://ytsaurus.tech/docs/en/api/python/userdoc.md#python_jobs_statistics)
* [Untyped Python operations](https://ytsaurus.tech/docs/en/api/python/userdoc.md#python_operations_untyped)
   - [Decorators](https://ytsaurus.tech/docs/en/api/python/userdoc.md#python_decorators_untyped)
   - [Formats](https://ytsaurus.tech/docs/en/api/python/userdoc.md#python_formats)
      - [Structured data representation](https://ytsaurus.tech/docs/en/api/python/userdoc.md#structured_data)
      - [Control attributes](https://ytsaurus.tech/docs/en/api/python/userdoc.md#control_attributes)
      - [Other formats](https://ytsaurus.tech/docs/en/api/python/userdoc.md#other_formats)
* [Other](https://ytsaurus.tech/docs/en/api/python/userdoc.md#other)
   - [gRPC](https://ytsaurus.tech/docs/en/api/python/userdoc.md#grpc)
   - [YSON bindings](https://ytsaurus.tech/docs/en/api/python/userdoc.md#yson_bindings)
* [Deprecated](https://ytsaurus.tech/docs/en/api/python/userdoc.md#legacy)
   - [Python3 and byte strings](https://ytsaurus.tech/docs/en/api/python/userdoc.md#python3_strings)

### Help { #pydoc }
The most up-to-date help on specific functions and their parameters is in the code.

To view a description of functions and classes in the interpreter, proceed as follows:

```bash
python
>>> import yt.wrapper as yt
>>> help(yt.run_sort)
```

### Examples { #examples }

* [Basic level](https://ytsaurus.tech/docs/en/api/python/examples.md#base)
   - [Reading and writing tables](https://ytsaurus.tech/docs/en/api/python/examples.md#read_write)
   - [Table schemas](https://ytsaurus.tech/docs/en/api/python/examples.md#table_schema)
   - [Simple map](https://ytsaurus.tech/docs/en/api/python/examples.md#simple_map)
   - [Sorting a table and a simple reduce operation](https://ytsaurus.tech/docs/en/api/python/examples.md#sort_and_reduce)
   - [Reduce with multiple input tables](https://ytsaurus.tech/docs/en/api/python/examples.md#reduce_multiple_output)
   - [Reduce with multiple input and output tables](https://ytsaurus.tech/docs/en/api/python/examples.md#reduce_multiple_input_output)
   - [mapreduce](https://ytsaurus.tech/docs/en/api/python/examples.md#map_reduce)
   - [MapReduce with multiple intermediate tables](https://ytsaurus.tech/docs/en/api/python/examples.md#map_reduce_multiple_intermediate_streams)
   - [Decorators for job classes](https://ytsaurus.tech/docs/en/api/python/examples.md#job_decorators)
   - [Working with files on the client and in operations](https://ytsaurus.tech/docs/en/api/python/examples.md#files)
   - [Grep](https://ytsaurus.tech/docs/en/api/python/examples.md#grep)
* [Advanced level](https://ytsaurus.tech/docs/en/api/python/examples.md#advanced)
   - [Batch queries](https://ytsaurus.tech/docs/en/api/python/examples.md#batch_queries)
   - [RPC](https://ytsaurus.tech/docs/en/api/python/examples.md#rpc)
* [Miscellaneous](https://ytsaurus.tech/docs/en/api/python/examples.md#misc)
   - [Data classes](https://ytsaurus.tech/docs/en/api/python/examples.md#dataclass)
   - [Context and managing writes to output tables](https://ytsaurus.tech/docs/en/api/python/examples.md#table_switches)
   - [Spec builders](https://ytsaurus.tech/docs/en/api/python/examples.md#spec_builder)
   - [Using gevent](https://ytsaurus.tech/docs/en/api/python/examples.md#gevent)
* [Untyped API](https://ytsaurus.tech/docs/en/api/python/examples.md#untyped_tutorial)
   - [Reading and writing tables](https://ytsaurus.tech/docs/en/api/python/examples.md#read_write_untyped)
   - [Simple map](https://ytsaurus.tech/docs/en/api/python/examples.md#simple_map_untyped)
   - [Sorting a table and a simple reduce operation](https://ytsaurus.tech/docs/en/api/python/examples.md#sort_and_reduce_untyped)
   - [Reduce with multiple input tables](https://ytsaurus.tech/docs/en/api/python/examples.md#reduce_multiple_output_untyped)
   - [Reduce with multiple input and output tables](https://ytsaurus.tech/docs/en/api/python/examples.md#reduce_multiple_input_output_untyped)
   - [MapReduce operation](https://ytsaurus.tech/docs/en/api/python/examples.md#map_reduce_untyped)
   - [Decorators for job classes and functions](https://ytsaurus.tech/docs/en/api/python/examples.md#job_decorators_untyped)
   - [Table switches and context](https://ytsaurus.tech/docs/en/api/python/examples.md#table_switches_untyped)
   - [Working with strings in Python3](https://ytsaurus.tech/docs/en/api/python/examples.md#yson_string_proxy)

<!-- ### Для разработчика { #fordeveloper }

  * [Контрибы](../../_includes/api/python/for_developer.md#contribs)
  * [Разбиение библиотеки на части в Аркадии](../../_includes/api/python/for_developer.md#peerdirs)
  * [Устройство и запуск тестов](../../_includes/api/python/for_developer.md#tests)
  * [Политика обновления библиотеки](../../_includes/api/python/for_developer.md#update_policy) -->

### FAQ { #faq }

This section contains answers to a number of frequently asked questions about the Python API. Answers to other frequently asked questions are in the [FAQ](https://ytsaurus.tech/docs/en/faq/index.md) section.

**Q: I installed the package via pypi, but I get the `yt: command not found` error.**
A: Try running the
`pip install ytsaurus-client --force-reinstall` command
, the log will most likely display a warning like `The script yt is installed in '...' which isn't on your PATH`. To solve the problem, you need to add the specified path to the PATH environment variable. To do this, run the following command:

```
echo 'export PATH="$PATH:<specified path>"' >> ~/.bashrc
source ~/.bashrc
```
Depending on the shell, the file may have a different name. The most common name on Mac is `~/.zshrc`.

**Q: Reading with retry ends with an error because of timeout.**
A: Most likely there are too many chunks in the table, you need to enlarge them. Use `yt merge --src table --dst table --spec "{combine_chunks=true}"`

**Q: The operation ends with a YSON error (for example: `YsonError: Premature end of stream`) and the web interface displays a YSON parsing error.**
A: The operation most likely writes to `stdout`. This is prohibited from being done explicitly in Python via `print, sys.stdout.write()` if the operation is not marked as `raw_io`, but it can be done by a third-party program, such as an archiver.

**Q: The Python library writes too much to stderr, how do I increase the level of logging?**
A: You can increase the level by setting the `YT_LOG_LEVEL="ERROR"` environment variable or by setting up the YTsaurus logger: `logging.getLogger("Yt").setLevel(logging.ERROR)`.

**Q:  I start an operation on Mac OS X, but jobs end with errors like `ImportError: ./tmpfs/modules/_ctypes.so: invalid ELF header`.**
A: Since the Python wrapper takes all Python operation dependencies with it to the cluster, binary .so and .pyc files arrive there too, which then cannot be loaded. Use a porto layer with your local environment and enable filtering of these files so that they do not end up on the cluster. For more information, see the [section](https://ytsaurus.tech/docs/en/api/python/userdoc.md#porto_layers).

**Q: Jobs end with the `Invalid table index N: expected integer in range [A,B]` error.**
A: The message means that you output a table index in the records and there is no corresponding table. This most often means that you have several input tables and one output table. The `@table_index` fields appear in the input records by default. To disable them, you can change the format: `yt.config["tabular_data_format"] = yt.YsonFormat(process_table_index=None)`. To learn more about the format, see the [section](https://ytsaurus.tech/docs/en/api/python/userdoc.md#python_formats). As an alternative, explicitly indicate in the specification (example for a map operation): `{"mapper": {"enable_input_table_index": False}}`.

**Q: The (ReadTimeout, HTTPConnectionPool(....): Read timed out.) error appears after the operation is completed.**
The message means that the operation stderr could not be downloaded due to network problems and even repeated queries didn't help. In that case, you should use the `ignore_stderr_if_download_failed` option which enables you to ignore stderr if you can't download it. We recommend using this option when writing production processes.

**Q: I get the `Yson bindings required` error.**
This means that YSON was selected as the input (output) format and bindings could not be imported in the job. To learn more about YSON and bindings, see the [section](https://ytsaurus.tech/docs/en/api/python/userdoc.md#yson). You need to install the bindings package and check that YSON bindings are not filtered out using `module_filter`. This is a dynamic yson_lib.so library that can easily be accidentally filtered out when filtering out all .so files. In addition, so that `yt_yson_bindings` that came in modules are not deleted, write `config["pickling"]["ignore_yson_bindings_for_incompatible_platforms"] = False` in the configuration file.
<!-- endsource: en/_includes/api/python/start.md -->