oct()

Convert an integer to its octal literal form — a string, not a number. Best known from Unix file permissions.

Built-in functionPython 1.0+Live demo
Common call
oct(0o755) # "0o755"
Returns
a str with "0o" prefix
Replaces
format(n, "o") when you also want the prefix
Watch out
floats are rejected — use int() first
oct(xx — Any integer (positive, negative, or zero). Objects with __index__ also accepted. Floats raise TypeError.type: int · required)
→ str

Demo

Live evaluation
Try:
Inputs
xintthe integer
Output
oct(8)
'0o10'

oct returns a STRING in the same form you would type an octal integer literal: "0o" prefix, digits 0..7. Negatives get a leading "-". This is a formatter, not a math operation — the value does not change, only its representation. Octal permissions like 0o755 read the same way in the source and in the output.

Parameters

NameTypeRequiredDescription
xintyesAny integer (positive, negative, or zero). Objects with __index__ also accepted. Floats raise TypeError.

Return value

str — A string in Python integer literal form: "0o" prefix, digits 0..7. Negatives get a "-0o" prefix.

Common patterns

Display file permissions
os.stat returns permissions as an integer; oct makes them readable.
import os, stat
mode = os.stat(path).st_mode
print(oct(stat.S_IMODE(mode)))
Round-trip via int
oct → str, int with base=8 → back. The prefix is optional on parse.
s = oct(0o755)     # "0o755"
n = int(s, 8)      # 493
Octal without the prefix
When you only want the digits, format is cleaner and lets you pad.
digits = format(0o755, "o")     # "755"
padded = format(0o12,  "04o")    # "0012"

Examples

1. Small integer
oct(8)
Returns
"0o10"
2. Zero
oct(0)
Returns
"0o0"
3. Unix chmod 755
oct(0o755)
Returns
"0o755"
4. Negative
oct(-8)
Returns
"-0o10"
5. Float raises
oct(1.5)
Returns
TypeError: 'float' object cannot be interpreted as an integer

Pitfalls

1. The "0o" prefix is included
Great for Python literals; in the way when you want a fixed-width octal dump or file-permission string without the prefix.
Prefix included
oct(0o755)
"0o755"
No prefix via format
format(0o755, "o")
"755"
2. Floats are rejected
oct only accepts integers. Truncate or round first.
Type error
oct(1.5)
TypeError: 'float' object cannot be interpreted as an integer
Truncate first
oct(int(1.5))
"0o1"
3. Python 2 vs Python 3 prefix
Python 2 used no prefix or just "0"; Python 3 uses "0o". Legacy code may parse the wrong form.
Python 2 form
int("0755", 8)  # works in both
493
Python 3 preferred
int("0o755", 8)  # explicit prefix
493
4. Result is a str, not a number
You cannot do arithmetic on the octal string. Parse it back if needed.
Type error
oct(7) + 1
TypeError: can only concatenate str (not "int") to str
Parse back
int(oct(7), 8) + 1
8

When to use

Use it
  • Displaying Unix file permissions in human form
  • Round-trippable output that int(s, 8) can parse back
  • Diagnostic messages where the prefix aids reading
Reach for something else
  • No prefix wanted → format(n, "o")
  • Fixed width / padding → format(n, "0No")
  • Bytes → bytes.hex() or bin/hex for byte values
  • Floats → truncate first

Notes

Complexity
O(log n) in the number of digits
Return
str — always with "0o" (or "-0o") prefix
CPython impl
Python/bltinmodule.c :: builtin_oct — delegates to __index__ then formats
Memory
Allocates one small string
Thread-safe
Yes — a pure computation

FAQ

Python 2 allowed both leading "0" and "0o" as octal literals — but "0" was ambiguous with integer literals starting with zero. Python 3 removed the "0" form to eliminate the ambiguity; oct() and int(s, 8) both use "0o" now.

History

1.0
oct() has been a builtin since Python 1.0.
3.0
Prefix changed to "0o" — matching the new octal literal syntax; the bare "0" form was removed to eliminate ambiguity.