Registry /
workflow / apache-airflow-providers-samba
Install & Compatibility
Where this runs
tested against v4.13.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 5.692s · 259.2MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 24.2s · import 5.340s · 257MB
259MB installed
● package 259MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
SambaHook
✓ from airflow.providers.samba.hooks.samba import SambaHook
✗ from airflow.hooks.samba_hook import SambaHook
The old `airflow.hooks.samba_hook` module is deprecated; use the provider-specific path.
SambaOperator
✓ from airflow.providers.samba.operators.samba import SambaOperator
This quickstart demonstrates how to use the `SambaOperator` to move a file on a Samba share. It requires an Airflow connection named `samba_default` to be configured with the Samba server details. The `operation` parameter can be 'move', 'read', 'write', or 'delete'.
from __future__ import annotations
import pendulum
from airflow.models.dag import DAG
from airflow.providers.samba.operators.samba import SambaOperator
with DAG(
dag_id="samba_file_operations_example",
start_date=pendulum.datetime(2023, 1, 1, tz="UTC"),
catchup=False,
schedule=None,
tags=["samba", "file_transfer"],
) as dag:
# This task assumes an Airflow Connection named 'samba_default' is configured.
# Configure a connection in the Airflow UI:
# Conn Id: samba_default
# Conn Type: Samba
# Host: <Samba Server IP/Hostname>
# Login: <Samba Username>
# Password: <Samba Password>
# Schema: <Optional default share name, e.g., 'share'>
# Extra: {"share_type": "posix"} or {"share_type": "windows"}
move_file_task = SambaOperator(
task_id="move_samba_file",
samba_conn_id="samba_default",
source_path="/source/path/file.txt",
destination_path="/destination/path/file.txt",
operation="move", # Other supported operations: 'read', 'write', 'delete'
)
Debug
Known issues
breakingProvider versions have specific minimum Apache Airflow core version requirements. For example, `apache-airflow-providers-samba` version 4.12.x requires Airflow 2.11+ due to internal API changes like the removal of the `apply_default` decorator.fixEnsure your Airflow core installation meets or exceeds the minimum version specified in the provider's changelog or documentation for the installed provider version. For 4.12.x, upgrade Airflow to 2.11+.
affects: 4.0.0+
gotchaWhen interacting with Windows Samba shares, using forward slashes (/) in paths may lead to `STATUS_INVALID_PARAMETER` errors. The underlying `smbclient` library often expects backslashes (\) or proper handling of path types.fixUse the `share_type='windows'` parameter in your Samba connection's 'Extra' field (`{"share_type": "windows"}`) or explicitly use Windows path separators (`\`) in your paths if the `share_type` is not set or defaults to 'posix'. affects: All versions
deprecatedThe old import path `airflow.hooks.samba_hook` has been deprecated.fixUpdate your imports to use `from airflow.providers.samba.hooks.samba import SambaHook`.
affects: <2.0.0 (provider versions)
gotchaSome users have reported issues with Kerberos authentication (`SpnegoError`) when using `SambaHook`, even when direct `smbclient` commands work outside Airflow.fixEnsure `pysmbclient` is up-to-date. Verify that Kerberos configuration (keytabs, krb5.conf) is correctly set up for the user running Airflow workers. Consider explicit `auth` parameter in 'Extra' field of the connection if supported by `pysmbclient`'s underlying mechanisms.
affects: Older Airflow 2.x versions (e.g., 2.2.0) with provider versions around 4.x.x.
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'airflow.providers.samba'
The 'apache-airflow-providers-samba' package is not installed or not accessible in the Python environment.
fixInstall the package using pip: 'pip install apache-airflow-providers-samba'.
ImportError: cannot import name 'SambaHook' from 'airflow.providers.samba.hooks.samba'
The 'SambaHook' class has been moved or renamed in the 'apache-airflow-providers-samba' package.
fixEnsure you are using the correct import statement: 'from airflow.providers.samba.hooks.samba import SambaHook'.
RuntimeError: The package 'apache-airflow-providers-samba' needs Apache Airflow 2.11.0+
The installed version of Apache Airflow is below the minimum required version for the 'apache-airflow-providers-samba' package.
fixUpgrade Apache Airflow to version 2.11.0 or higher.
STATUS_INVALID_PARAMETER when connecting to a Windows share using the samba provider I am receiving a STATUS_INVALID_PARAMETER error when I try to use the 'listdir' function.
This issue, particularly observed with `listdir` on Windows shares, is often due to the SambaHook internally generating paths with forward slashes (/) instead of the backward slashes (\) expected by Windows SMB shares in some contexts.
fixEnsure your `apache-airflow-providers-samba` is updated to a recent version (e.g., 4.10.x or higher), as fixes for Windows path handling have been implemented. If the issue persists with an updated provider, you might need to test direct `smbclient` calls with explicit backward slashes to confirm the path formatting requirement for your specific Samba server setup.
ImportError: cannot import name 'link' from 'smbclient'
This error occurs when the `airflow.providers.samba.hooks.samba` module attempts to import `link` from the `smbclient` library, but the installed `smbclient` version (or a conflicting package) does not expose this function, or there's a local naming conflict with another `smbclient.py` file.
fixVerify that `pysmbclient` (the underlying library for `smbclient`) is installed and meets the required version (e.g., `>=0.1.3`). Check for any custom `smbclient.py` files in your Python path that might be shadowing the official package. Reinstalling `apache-airflow-providers-samba` might resolve dependency mismatches: `pip install --upgrade --force-reinstall apache-airflow-providers-samba`.
Upgrade
Version history
4.13.0latest on PyPI · released Aug 23, 2026
Audit
Dependencies
apache-airflowrequiredCore Airflow functionality; requires Airflow 2.11+ for provider version 4.12.x.
pysmbclientrequiredUnderlying Python client for SMB/CIFS protocol interactions.