# xarray.concat

### xarray.concat(objs, dim, data_vars=all, coords=different, compat=equals, positions=None, fill_value=<NA>, join=outer, combine_attrs='override', create_index_for_new_dim=True)[[source]](https://github.com/pydata/xarray/blob/main/xarray/structure/concat.py#L90-L341)

Concatenate xarray objects along a new or existing dimension.

* **Parameters:**
  * **objs** ([sequence](https://docs.python.org/3/glossary.html#term-sequence) of [`DataArray`](xarray.DataArray.html.md#xarray.DataArray), [`Dataset`](xarray.Dataset.html.md#xarray.Dataset) or [`DataTree`](xarray.DataTree.html.md#xarray.DataTree)) – xarray objects to concatenate together. Each object is expected to
    consist of variables and coordinates with matching shapes except for
    along the concatenated dimension.
  * **dim** (`Hashable` or [`Variable`](xarray.Variable.html.md#xarray.Variable) or [`DataArray`](xarray.DataArray.html.md#xarray.DataArray) or [`pandas.Index`](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.Index.html#pandas.Index)) – Name of the dimension to concatenate along. This can either be a new
    dimension name, in which case it is added along axis=0, or an existing
    dimension name, in which case the location of the dimension is
    unchanged. If dimension is provided as a Variable, DataArray or Index, its name
    is used as the dimension to concatenate along and the values are added
    as a coordinate.
  * **data_vars** (`{"minimal", "different", "all", None}` or [`list`](https://docs.python.org/3/builtins/stdtypes.html#list) of [`str`](https://docs.python.org/3/builtins/stdtypes.html#str), *default*: `"all"`) –

    These data variables will be concatenated together:
    : * “minimal”: Only data variables in which the dimension already
        appears are included.
      * “different”: Data variables which are not equal (ignoring
        attributes) across all datasets are also concatenated (as well as
        all for which dimension already appears). Beware: this option may
        load the data payload of data variables into memory if they are not
        already loaded.
      * “all”: All data variables will be concatenated.
      * None: Means `"all"` if `dim` is not present in any of the `objs`,
        and `"minimal"` if `dim` is present in any of `objs`.
      * list of str: The listed data variables will be concatenated, in
        addition to the “minimal” data variables.

    If objects are DataArrays, data_vars must be “all” or None.
  * **coords** (`{"minimal", "different", "all"}` or [`list`](https://docs.python.org/3/builtins/stdtypes.html#list) of [`str`](https://docs.python.org/3/builtins/stdtypes.html#str), *default*: `"different"`) –

    These coordinate variables will be concatenated together:
    : * “minimal”: Only coordinates in which the dimension already appears
        are included.
      * “different”: Coordinates which are not equal (ignoring attributes)
        across all datasets are also concatenated (as well as all for which
        dimension already appears). Beware: this option may load the data
        payload of coordinate variables into memory if they are not already
        loaded.
      * “all”: All coordinate variables will be concatenated, except
        those corresponding to other dimensions.
      * list of str: The listed coordinate variables will be concatenated,
        in addition to the “minimal” coordinates.
  * **compat** (`{"identical", "equals", "broadcast_equals", "no_conflicts", "override"}`,              default: `"equals"`) – String indicating how to compare non-concatenated variables of the same name for
    potential conflicts. This is passed down to merge.
    - “broadcast_equals”: all values must be equal when variables are
      broadcast against each other to ensure common dimensions.
    - “equals”: all values and dimensions must be the same.
    - “identical”: all values, dimensions and attributes must be the
      same.
    - “no_conflicts”: only values which are not null in both datasets
      must be equal. The returned dataset then contains the combination
      of all non-null values.
    - “override”: skip comparing and pick variable from first dataset
  * **positions** ([`None`](https://docs.python.org/3/builtins/constants.html#None) or [`list`](https://docs.python.org/3/builtins/stdtypes.html#list) of `integer arrays`, *optional*) – List of integer arrays which specifies the integer positions to which
    to assign each dataset along the concatenated dimension. If not
    supplied, objects are concatenated in the provided order.
  * **fill_value** ([scalar](../user-guide/terminology.html.md#term-scalar) or [dict-like](https://docs.python.org/3/glossary.html#term-mapping), *optional*) – Value to use for newly missing values. If a dict-like, maps
    variable names to fill values. Use a data array’s name to
    refer to its values.
  * **join** (`{"outer", "inner", "left", "right", "exact"}`, *default*: `"outer"`) – String indicating how to combine differing indexes
    (excluding dim) in objects
    - “outer”: use the union of object indexes
    - “inner”: use the intersection of object indexes
    - “left”: use indexes from the first object with each dimension
    - “right”: use indexes from the last object with each dimension
    - “exact”: instead of aligning, raise ValueError when indexes to be
      aligned are not equal
    - “override”: if indexes are of same size, rewrite indexes to be
      those of the first object with that dimension. Indexes for the same
      dimension must have the same size in all objects.
  * **combine_attrs** (`{"drop", "identical", "no_conflicts", "drop_conflicts", "override"}` or [`callable()`](https://docs.python.org/3/builtins/functions.html#callable), *default*: `"override"`) – A callable or a string indicating how to combine attrs of the objects being
    merged:
    - “drop”: empty attrs on returned Dataset.
    - “identical”: all attrs must be the same on every object.
    - “no_conflicts”: attrs from all objects are combined, any that have
      the same name must also have the same value.
    - “drop_conflicts”: attrs from all objects are combined, any that have
      the same name but different values are dropped.
    - “override”: skip comparing and copy attrs from the first dataset to
      the result.

    If a callable, it must expect a sequence of `attrs` dicts and a context object
    as its only parameters.
  * **create_index_for_new_dim** ([`bool`](https://docs.python.org/3/builtins/functions.html#bool), *default*: [`True`](https://docs.python.org/3/builtins/constants.html#True)) – Whether to create a new `PandasIndex` object when the objects being
    concatenated contain scalar variables named `dim`.
* **Returns:**
  **concatenated** ([`type`](https://docs.python.org/3/builtins/functions.html#type) of `objs`)

#### SEE ALSO
[`merge`](xarray.merge.html.md#xarray.merge)

### Examples

<div class="try_examples_button_container"><button class="try_examples_button" onclick="window.tryExamplesShowIframe('dfe90061-90cc-4272-8b0b-d4695b2f15f9','3a711e8b-8e88-4e0c-8240-87a3332e46a1','1c7366b4-b805-42c9-8dc8-6fe93a3cc7fe','../lite/tree/../notebooks/index.html?path=81696ab6_ccae_44b2_a561_d5c653476c76.ipynb','None')">Try it in your browser!</button></div>
```pycon
>>> da = xr.DataArray(
...     np.arange(6).reshape(2, 3), [("x", ["a", "b"]), ("y", [10, 20, 30])]
... )
>>> da
<xarray.DataArray (x: 2, y: 3)> Size: 48B
array([[0, 1, 2],
       [3, 4, 5]])
Coordinates:
  * x        (x) <U1 8B 'a' 'b'
  * y        (y) int64 24B 10 20 30
```

```pycon
>>> xr.concat([da.isel(y=slice(0, 1)), da.isel(y=slice(1, None))], dim="y")
<xarray.DataArray (x: 2, y: 3)> Size: 48B
array([[0, 1, 2],
       [3, 4, 5]])
Coordinates:
  * x        (x) <U1 8B 'a' 'b'
  * y        (y) int64 24B 10 20 30
```

```pycon
>>> xr.concat([da.isel(x=0), da.isel(x=1)], "x", coords="minimal")
<xarray.DataArray (x: 2, y: 3)> Size: 48B
array([[0, 1, 2],
       [3, 4, 5]])
Coordinates:
  * x        (x) <U1 8B 'a' 'b'
  * y        (y) int64 24B 10 20 30
```

```pycon
>>> xr.concat([da.isel(x=0), da.isel(x=1)], "new_dim", coords="all")
<xarray.DataArray (new_dim: 2, y: 3)> Size: 48B
array([[0, 1, 2],
       [3, 4, 5]])
Coordinates:
    x        (new_dim) <U1 8B 'a' 'b'
  * y        (y) int64 24B 10 20 30
Dimensions without coordinates: new_dim
```

```pycon
>>> xr.concat(
...     [da.isel(x=0), da.isel(x=1)],
...     pd.Index([-90, -100], name="new_dim"),
...     coords="all",
... )
<xarray.DataArray (new_dim: 2, y: 3)> Size: 48B
array([[0, 1, 2],
       [3, 4, 5]])
Coordinates:
  * new_dim  (new_dim) int64 16B -90 -100
    x        (new_dim) <U1 8B 'a' 'b'
  * y        (y) int64 24B 10 20 30
```

# Concatenate a scalar variable along a new dimension of the same name with and without creating a new index

```pycon
>>> ds = xr.Dataset(coords={"x": 0})
>>> xr.concat([ds, ds], dim="x")
<xarray.Dataset> Size: 16B
Dimensions:  (x: 2)
Coordinates:
  * x        (x) int64 16B 0 0
Data variables:
    *empty*
```

```pycon
>>> xr.concat([ds, ds], dim="x").indexes
Indexes:
    x        Index([0, 0], dtype='int64', name='x')
```

```pycon
>>> xr.concat([ds, ds], dim="x", create_index_for_new_dim=False).indexes
Indexes:
    *empty*
```

<div id="1c7366b4-b805-42c9-8dc8-6fe93a3cc7fe" class="try_examples_outer_iframe  hidden"><div class="try_examples_button_container"><button class="try_examples_button" onclick="window.tryExamplesHideIframe('dfe90061-90cc-4272-8b0b-d4695b2f15f9','1c7366b4-b805-42c9-8dc8-6fe93a3cc7fe')">Go Back</button><button class="try_examples_button" onclick="window.openInNewTab('dfe90061-90cc-4272-8b0b-d4695b2f15f9','1c7366b4-b805-42c9-8dc8-6fe93a3cc7fe')">Open In Tab</button></div><div id="3a711e8b-8e88-4e0c-8240-87a3332e46a1" class="jupyterlite_sphinx_iframe_container"></div></div><script>document.addEventListener("DOMContentLoaded", function() {window.loadTryExamplesConfig("../try_examples.json");});</script>