oschmod
oschmod sets consistent file permissions across Windows, Linux and macOS.
oschmod TL;DR
oschmod brings chmod functionality to Windows, macOS, and Linux! If you're not familiar, chmod is a handy macOS and Linux-only tool for setting file permissions.
Prior to oschmod, Windows file permissions couldn't be set in the familiar chmod way. Tools did not translate chmod-style permissions into Windows-style file permissions. Even though Python's os.chmod() sets read, write, and execute file permissions, on Windows, os.chmod() basically has no effect. Even worse, Python on Windows gives no warnings or errors. If you think you set file permissions on Windows with os.chmod(), you're wrong!
oschmod allows you to set consistent file permissions in a consistent way across platforms.
- Read more about oschmod on Medium
- For more background, have a look at the oschmod Wiki.
Installation
$ pip install oschmod
Or with conda:
$ conda install -c conda-forge oschmod
oschmod requires Python 3.11 or newer. On Windows, it depends on pywin32, which is installed automatically.
GNU Documentation
oschmod changes the file mode bits of each given file according to mode, which can be either a symbolic representation of changes to make, or an octal number representing the bit pattern for the new mode bits.
The format of a symbolic mode is [ugoa...][[-+=][perms...]...], where perms is either zero or more letters from the set rwxXst, or a single letter from the set ugo. Multiple symbolic modes can be given, separated by commas.
A combination of the letters ugoa controls which users' access to the file will be changed: the user who owns it (u), other users in the file's group (g), other users not in the file's group (o), or all users (a). If none of these are given, the effect is as if a were given. (GNU chmod also applies the umask in that case; oschmod doesn't.)
The letters rwxXst select file mode bits for the affected users: read (r), write (w), execute or search for directories (x), execute/search only if the file is a directory or already has execute permission for some user (X), set user or group ID on execution (s), and restricted deletion flag or sticky bit (t). Instead of one or more of these letters, you can specify exactly one of the letters ugo: the permissions granted to the user who owns the file (u), the permissions granted to other users who are members of the file's group (g), and the permissions granted to users that are in neither of the two preceding categories (o).
On Windows, s and t have no effect.
(Modified from the GNU manpage for chmod.)
Command line interface
oschmod brings the ability to set consistent file permissions using the command line to Windows, macOS, and Linux platforms. If you are familiar with chmod, oschmod works similarly, albeit with fewer options.
$ oschmod -h
usage: oschmod [options] MODE FILE...
oschmod [options] --reference=RFILE FILE...
Change the mode (permissions) of files and directories
positional arguments:
MODE FILE MODE is octal (e.g., 640) or symbolic (e.g.,
u=rw,g=r,o=, or a+rX); FILE is one or more files or
directories (MODE is omitted with --reference)
options:
-h, --help show this help message and exit
-R, --recursive apply mode recursively
-H with -R, follow the object if it is a symlink, but no
links below it (default)
-L with -R, follow every symlink (changes link targets,
even outside the tree)
-P with -R, follow no symlinks
-v, --verbose verbose: show each object as its mode is set; repeat
(-vv) to also show old and new modes
-c, --changes like -vv, but report only objects whose mode changed
(overrides -v)
-f, --silent, --quiet
don't print errors for individual objects (the exit
status is still 1)
--reference RFILE use RFILE's mode instead of a MODE argument (symlinks
are followed)
--other-sid SID Windows only: SID that receives "other" permissions
(default: S-1-5-32-545, the built-in Users group)
--version show program's version number and exit
You can also run it as python -m oschmod.
Command line examples
You can use symbolic (e.g., "u+rw") or octal (e.g., "600") representations of modes. Multiple mode modifications can be made in a single call by separating modifiers with commas.
Symbolic representation examples
Symbolic representation mode modifiers have three parts:
- whom: To whom does the modification apply? You can include zero or more of
[ugoa]*whereais for all,uis for the file owner (i.e., "user"),gis for the file group, andois for others. In other words,ugois equivalent toa. Also, if you do not provide a "whom," oschmod assumes you meana(everyone). - operation: Which operation should be applied?
+adds permissions,-removes permissions, and=sets permissions regardless of previous permissions. You can chain operations for the same "whom" (e.g.,u+r-x); each one applies to the result of the one before. - permission: Which permission or permissions will be affected? You can include zero or more of
[rwxXst]*whereris for read,wis for write,xis for execute,Xis for execute only on directories and files that are already executable,sis set-user-ID or set-group-ID, andtis the sticky bit. Or you can give one ofu,g, oroto copy that class's current permissions (e.g.,g=u). If you do not include a permission with+or-(e.g.,u-), the modifier has no effect. However, if you use no permissions with=(e.g.,o=), all permissions are removed.
Example 1: To give everyone execute permissions on a file (all of these are equivalent):
$ oschmod +x <file name>
$ oschmod a+x <file name>
$ oschmod ugo+x <file name>
Example 2: To remove read, write, and execute permissions from the file group and all others (these are equivalent):
$ oschmod go-rwx <file name>
$ oschmod go= <file name>
Example 3: To give the file owner read and execute permissions, and remove execute permissions from the group and all others:
$ oschmod u+rx,go-x <file name>
Example 4: To give everyone all permissions, and then remove execute write from the group, and execute from all others:
$ oschmod a+rwx,g-w,o-x <file name>
Example 5: To make a tree readable by everyone, and make directories (but not ordinary files) enterable:
$ oschmod -R a+rX <directory name>
Example 6: To give the group the same permissions as the owner, minus write:
$ oschmod g=u-w <file name>
Octal representation examples
For more about what octal representations mean, see this article on Medium.
Example 7: To give everyone read, write, and execute permissions on a file:
$ oschmod 777 <file name>
Example 8: To lock down a file to just give the file owner read, write, and execute permissions and deny all permissions to everyone else:
$ oschmod 700 <file name>
Verbose output
Example 9: Show each object as its mode is set (-v), or show old and new modes too (-vv):
$ oschmod -vv 600 secrets.txt
secrets.txt: 0o644 (rw-r--r--) -> 0o600 (rw-------)
Example 10: Report only objects whose mode actually changed (-c), and hide per-file errors (-f; the exit status is still 1 if anything failed):
$ oschmod -c -R u=rwX,go= project
project/notes.txt: 0o644 (rw-r--r--) -> 0o600 (rw-------)
$ oschmod -f 600 *.pem
Example 11: Give files the same mode as another file:
$ oschmod --reference=template.cfg app.cfg db.cfg
Recursion and symlinks
With -R, symlinks found inside the tree are not followed, so nothing outside the tree is changed. This is the same as GNU chmod -R and is the safe choice, especially when running as root or Administrator on a directory that others can write to. On Windows, directory junctions are treated the same way as symlinks.
-H(default): if the object you name is a symlink to a directory, follow it, but no links below it.-L: follow every symlink, changing link targets wherever they are. Use this only for trees you control, for example a deployment directory that links to shared storage. Directory cycles are skipped.-P: follow no symlinks; a symlink to a directory given on the command line is left alone.
If an object can't be changed, oschmod prints an error, keeps going, and exits with status 1 at the end. A directory that can't be listed because of its current mode (e.g., 000) gets its new mode first, so oschmod -R u+rwx mydir can repair it.
Python usage
You can use oschmod from Python code. Any of the command line examples above will work very similarly. For example, Example 4 above, in Python code, would look like this:
import oschmod
oschmod.set_mode("myfile", "a+rwx,g-w,o-x")
Example 7 above, in Python code, could be done in two ways:
import oschmod
oschmod.set_mode("myfile", "777")
oschmod.set_mode("myfile", 0o777)
oschmod is compatible with bitwise permissions as defined in the stat module. To give a file's owner read, write, and execute permissions and deny the group and others any permissions (i.e., equivalent of 700):
import oschmod
import stat
oschmod.set_mode("myfile", stat.S_IRUSR | stat.S_IWUSR | stat.S_IXUSR)
Replacing os.chmod() with oschmod should usually be an easy drop-in replacement. Replacement will allow you to get consistent file permission settings on Windows, macOS, and Linux:
If this is your Python code using os.chmod():
import os
os.chmod("myfile1", "u+x")
os.chmod("myfile2", 0o777)
The replacement using oschmod is very similar:
import oschmod
oschmod.set_mode("myfile1", "u+x")
oschmod.set_mode("myfile2", 0o777)
get_mode() returns only the read/write/execute bits (0o777). On macOS and Linux, use get_full_mode() to also include set-user-ID, set-group-ID, and sticky bits (0o7777). Symbolic + and - (e.g., g+w) leave those special bits as they are. As in GNU chmod, = clears them for the classes it sets: u= clears set-user-ID, g= set-group-ID, and o= the sticky bit. Directories keep their set-user-ID and set-group-ID bits.
An invalid mode string raises oschmod.ModeError, a ValueError.
Creating private files
Creating a file and then calling set_mode() leaves a moment when the file has default permissions; on Windows, those are usually inherited from the folder. To create a file that has its final permissions from the start, use oschmod.open_new(). It works like open(path, "x"): it fails with FileExistsError if anything, including a symlink, already exists at the path.
import oschmod
with oschmod.open_new("token.json", "w", perms=0o600) as f:
f.write(secret)
oschmod.mkdir("keys", perms=0o700)
open_new()returns an ordinary file object, likeopen().modecan be"w","x", or"a", plus optional"b"/"t"and"+". It also takesopen()'sbuffering,encoding,errors, andnewline. Invalid arguments raise before anything is created.oschmod.mkdir()fails withFileExistsErrorlikeos.mkdir(), and never follows a symlink.permstakes any modeset_mode()accepts, such as0o600,"600", or"u=rw". The umask doesn't apply, so the result is exactlyperms.- On Windows, the file or directory is created with the same protected DACL that
set_mode()writes.other_sidworks as it does forset_mode().
To give one file the same mode as another, use oschmod.copy_mode(src, dst). Unlike shutil.copymode(), it also works on Windows.
set_mode_recursive() skips symlinks below the path by default. Pass follow_symlinks=True to follow them. Errors stop the walk unless you pass on_error, which is called with the path and exception for each failure:
import oschmod
failures = []
oschmod.set_mode_recursive(
"mydir", "u=rw,go=r", "u=rwx,go=rx", on_error=lambda path, exc: failures.append(path)
)
Paths can be strings or any path-like object, such as pathlib.Path:
from pathlib import Path
import oschmod
oschmod.set_mode(Path("myfile"), 0o600)
Windows notes
Windows has no owner/group/other mode bits, so oschmod maps them to ACL entries:
- Owner is the file's owner SID, and group is the file's primary group SID.
- Others is the built-in Users group (
S-1-5-32-545) by default. To use a different account, passother_sid(for example,"S-1-5-11"for Authenticated Users). In Python, useoschmod.set_mode(path, "o+r", other_sid="S-1-5-11"); on the command line, use--other-sid S-1-5-11. - Setting a mode replaces the object's DACL with explicit entries and marks it protected, so permissions are no longer inherited from the parent folder, including after later changes to the parent. Any existing entry for the local SYSTEM account is kept.
- Set-user-ID, set-group-ID, and sticky bits have no Windows equivalent and are ignored there.
- When reading a mode, only entries for the owner, the group, and the "other" account count. Entries for groups that include everyone in "other" also count: Everyone always, and Authenticated Users when "other" is the default Users. Entries for any other account, such as Administrators, are ignored when reading, and removed when a mode is set (SYSTEM excepted). Pass the same
other_sidtoget_mode()that you use withset_mode(). - "Write" lets an account change the file's contents, not its permissions or owner. The owner can always change permissions.
- If one account fills two roles (for example, the owner is also the group), it gets the bits of the first role, in the order owner, group, other, as on POSIX.
ACCESS_DENIEDentries are not considered when reading a mode.
Metadata
Release files for oschmod 0.7.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| oschmod-0.7.0.tar.gz | 52.1 kB | With provenance | Details for oschmod-0.7.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| oschmod-0.7.0-py3-none-any.whl | Python 3 | none | any | Details for oschmod-0.7.0-py3-none-any.whl |
Total release size: 82.9 kB
Release files / oschmod-0.7.0.tar.gz
| Download URL | oschmod-0.7.0.tar.gz |
|---|---|
| Size | 52.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
e3af9400b9c29b37199290d8d9b944b5c2fc7b887c65b63aba082f2d24e0c90e
|
|
BLAKE2b-256 checksum How to use checksums |
54efad77c29305872e0084361e5159e3a2765c5ef2f2469454f2ccaf9e31253c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 29, 2026.
Transparency logRelease files / oschmod-0.7.0-py3-none-any.whl
| Download URL | oschmod-0.7.0-py3-none-any.whl |
|---|---|
| Size | 30.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
be55350e06a76fa383ed4bddbdd2a7d8d5cacba1bea37ade2543183d103bf998
|
|
BLAKE2b-256 checksum How to use checksums |
d789c3725d94b5f1e590af2c78c0b57c933abaecd352261d0cdd48d6de286bea
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 29, 2026.
Transparency logSecurity for oschmod 0.7.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for oschmod-0.7.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 29, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.