smbclient-ng: an interactive SMB shell in Python

A prompt on a remote share, not a file manager

smbclient-ng describes itself as a fast and user friendly way to interact with SMB shares, and it is a Python program with a command line and an interactive session.

The architecture is visible in the packaging. The project metadata declares two console entry points, smbclientng and smbng, both pointing at the same callable, smbclientng.console:run, and the package itself is smbclientng. The repository has a smbclientng/ package directory, a testing/ directory and a documentation/ directory that is generated rather than hand written, since the Makefile has a docs target that runs pdoc over the package with PDOC_ALLOW_EXEC=1 and writes markdown into ./documentation/.

The dependency list tells you what the protocol handling is built on. It is impacket at 0.10.0 or later, with rich at 13.0.0 or later for the terminal output, charset-normalizer for encoding and pefile for reading the Portable Executable files that often turn up in a Windows share. The project requires Python 3.9 or later and is built with poetry-core 2.x.

The project is GPL-3.0, with the package metadata saying GPL-3.0-or-later. The last push was on 2026-09-29, and the releases show a steady line with occasional bigger changes: 2.1.7 in November 2024 with bug fixes and the acls command added, 3.0.0 in February 2026 with Kerberos authentication, and 3.1.0 in July 2026 with bug fixes.

One note in the README sits above the feature list and changes the picture for a new user. It says to check out the new smbclient-ng written in Go, faster and cross platform by default, and points at a repository under TheManticoreProject. The author is steering people away from this Python implementation, and that is the single most important line in the README for anybody deciding what to install.

Remote commands and their local twins

The feature list is long, and it is worth reading as two families. There is a set of commands that act on the remote share, and there is a set with an l prefix that act on the local filesystem instead.

The remote set covers the operations you would expect. cat gets the contents of a file, head and tail get the first or last n lines, bat pretty prints the contents of a file, bhead and btail pretty print the first or last n lines. cd changes the current working directory, dir and ls list the current remote working directory, tree displays a tree view of the remote directories, and metadata gets metadata about a file or directory. mkdir and rmdir create and remove remote directories, rm removes a remote file, put puts a local file or directory into a remote directory and get takes a remote file, with the -r flag on both for recursion.

The local set mirrors the shell rather than SMB. lcat prints the contents of a local file, lbat pretty prints one, lcd changes the current local directory, lls lists the current local directory, lpwd shows it, ltree displays a tree view of the local directories, lmkdir creates a local directory, lrmdir removes one, lrm removes a local file, lcp creates a copy of a local file and lrename renames one.

The connection commands are there too. connect and reconnect establish or re-establish the connection, which the descriptions call useful if the connection timed out, close closes the SMB connection to the remote machine, and use selects a share, with shares listing the shares the remote machine serves and info giving information about the server or a share.

Three of the commands are less obvious. sessions manages the SMB sessions, with the syntax sessions [interact|create|delete|execute|list]. module loads a specific module for additional functionalities, which is how the tool extends itself. And reset resets the TTY output, which the README describes as useful if it was broken after printing a binary file on stdout, which is the sort of detail that tells you this tool has been used on real shares.

Authentication is where this differs from the system client

The authentication options in the usage output are the reason to reach for this tool rather than whatever your operating system ships, and they are grouped by the program itself into a section called Authentication and Connection and another called Secrets.

The connection part is ordinary. -H takes the target SMB server IP or hostname, -P the port, with a default of 445, -d the authentication domain and -u the username.

The secrets part is where the tool earns its place. -p takes a password, and because it is written as -p [PASSWORD] with the value in brackets, passing it without a value means the tool prompts for it. --no-pass says do not prompt for a password. --hashes takes an NT or LM hash, in the form [LMHASH:]NTHASH, which is the credential format you recover from a target rather than one you know. --aes-key takes a hex encoded AES key for Kerberos authentication, and -k selects Kerberos with --kdcHost giving the fully qualified domain name of the key distribution centre.

There is also a --debug flag and a --no-colors flag, which matters for a tool that is expected to be used in a pipeline as well as interactively, and a -T timeout with a default of 3 seconds for SMB connections, a -l logfile option, and an -a advertised name option that sets the machine name presented to the server.

For scripted use there are two more options that are easy to miss. -C executes a command, and -S runs a startup script of commands, both of which combine with -N, the non interactive mode, to make the tool a scriptable client rather than a prompt. The interactive mode also keeps a history, with a history command, and the exit command is exit.

The one thing to be careful about is that -p with a value on the command line puts the password into your shell history and into the process list. The prompt mode exists for a reason.

Installing it, and the Python versions you will meet

The install section gives three routes, and they are the standard ones for a Python tool that is also a command line program.

With pip:

python3 -m pip install smbclientng

With pip3:

pip3 install smbclientng

Or with pipx, which is the one to prefer if you do not want the package and its dependencies in your system Python environment:

pipx install smbclientng

Note that the package name on the index is smbclientng, without the hyphen, while the project and the command are smbclient-ng and smbclientng. The importable package is smbclientng too, so the two console scripts, smbclientng and smbng, are both installed.

The build side of the repository is a Makefile that reveals a few habits. Every pip call in it includes --break-system-packages, which is the flag recent Python versions need when installing into a distribution managed environment, and the same flag appears in the uninstall target. The build target uninstalls the project, installs it with the build extra, and then runs python3 -m build --wheel, and the upload target installs the twine extra and runs python3 -m twine upload dist/*.

The lint setup is a normal modern Python trio: flake8 with a max line length of 88 and E501 and E203 ignored, black in check mode with the diff, and isort in check-only mode. There is a lint-fix target that runs the same three in write mode.

The repository also carries poetry.lock and poetry.toml, so the dependency set is pinned even though the published metadata allows a range, with impacket at 0.10.0 or later and rich at 13.0.0 or later being the two that matter.

The Go rewrite the README points you at

The note at the top of the README is the most consequential line in the document, and it deserves to be read as a recommendation rather than as a footnote.

It says to check out the new smbclient-ng written in Go, faster and cross platform by default, and links to the repository under TheManticoreProject. The new implementation is described as faster and cross platform by default, which is a differentiator the Python version cannot claim, since this one needs a Python 3.9 or later interpreter and the impacket, rich, charset-normalizer and pefile packages to be importable.

The difference in approach between the two is worth spelling out, because it decides which one you install. The Python implementation is a package you put into an environment, and it inherits the reach of its dependencies, which is why the project is comfortable on a Linux or macOS box where those wheels exist and less comfortable elsewhere. The Go implementation is a compiled binary that runs where the binary runs, and the README's own framing, faster and cross platform by default, is the argument for it.

The other dimension is maintenance. The Python version has a well documented command set, a generated documentation directory, a testing directory and a Makefile with lint and release targets, and it ships on PyPI. The Go version is a separate repository that this README does not describe, so the command set and the options documented here are the Python ones, and if you switch, you are switching to a tool whose interface you have not read yet.

So the practical order is this. If you need a quick script against a share today, the Python tool is here and it is installed in one command. If you are choosing a tool for something you will keep, read the Go version first, because the author has already told you which one he would rather you used.

Mounting a share, and when to stop

Two commands in the list stand out from the file transfer set, and both are about bridging the gap between the protocol and the local machine.

mount creates a mount point of the remote share on the local machine, and umount removes it. Everything else in the list either reads or writes files, but mount makes the share look like a local path, which means a tool that only understands files can use it. The pair is what turns this from a client into a bridge.

sizeof recursively computes the size of a folder, which sounds trivial and is not, because it has to walk the whole tree over the network.

The other feature that catches the eye is acls, which lists the ACLs of files and folders in the current directory. It was added in the 2.1.7 release in November 2024, and it is the sort of command that distinguishes a tool built for administering shares from one built for copying files.

As for when this is the wrong tool, the case is straightforward. If you are on Windows, the operating system already has a client and the smbclient-ng value is the extra commands and the scripting, not the basic transfer. If you want to mount a share permanently with credentials and a mount point at boot, that is an operating system and a configuration task rather than a session in a Python prompt, and the mount command here is a convenience inside a live session rather than a system integration. And if you are building something long lived, the README's own pointer to the Go implementation is the thing to act on.

One more practical note for scripting. The reset command exists because printing a binary file to stdout can leave your terminal in a broken state, and in a script that pipes a file through cat you want the terminal restored afterwards. It is a small sign of a tool that has been used against real data, and it is worth remembering when you chain commands.

Editorial conclusion

Adopt smbclient-ng if you need a scripted, non-interactive way to work with SMB shares from a Linux or macOS box, and if your environment needs Kerberos, hash based or AES key authentication rather than a plain password. Do not adopt it if you are on Windows, where the built in client already exists, and do not adopt it as a long term project dependency without reading the note in the README about the Go rewrite, which the author recommends for speed and cross platform use. Verify first that the impacket version you get satisfies the project, that the timeout default of 3 seconds is right for your links, and that the credentials you pass on the command line do not end up in a shell history.

Frequently asked questions

Official sources

1. License: GPL-3.0
2. p0dalirius/smbclient-ng on GitHub
3. Project website
4. README
5. Releases