Repository navigation
Deprecate utcnow and utcfromtimestamp #103857
Description
Activity
I've gone ahead and done some benchmarks for the most common legitimate use case I've seen for
utcnowandutcfromtimestamp, which is getting a naïvedatetimeand immediately formatting it to a string with no time zone offset. The alternatives are considerably slower, though I don't know how important that is for real life use cases:>>> %timeit datetime.now(UTC).replace(tzinfo=None).isoformat(' ') 2.15 µs ± 19.9 ns per loop (mean ± std. dev. of 7 runs, 100,000 loops each) >>> %timeit datetime.now(UTC).isoformat(' ')[:-6] 1.61 µs ± 23.7 ns per loop (mean ± std. dev. of 7 runs, 1,000,000 loops each) >>> %timeit datetime.utcnow().isoformat(' ') 919 ns ± 5.23 ns per loop (mean ± std. dev. of 7 runs, 1,000,000 loops each)
As an example of how this changes the speed in a real-life application, here are the before and after measurements for the change to
http.cookiejar.time2isoz:>>> t = datetime.now().timestamp() >>> %timeit cookiejar(None) # Uses datetime.now 1.52 µs ± 16.2 ns per loop (mean ± std. dev. of 7 runs, 1,000,000 loops each) >>> %timeit cookiejar_utc(None) # Uses datetime.utcnow 1.32 µs ± 6.72 ns per loop (mean ± std. dev. of 7 runs, 1,000,000 loops each) >>> %timeit cookiejar(t) # Uses datetime.fromtimestamp 1.77 µs ± 24.2 ns per loop (mean ± std. dev. of 7 runs, 1,000,000 loops each) >>> %timeit cookiejar_utc(t) # Uses datetime.utcfromtimestamp 1.4 µs ± 5.75 ns per loop (mean ± std. dev. of 7 runs, 1,000,000 loops each)
I'm still more or less convinced that this is useful to do, and I'd like to see if anyone complains that it's a major problem after the deprecation before worrying about these micro-optimizations.
- added a commit that references this issue
on Apr 27, 2023 - added a commit that references this issue
on May 12, 2023 I think we're all set here! 🚀
- added a commit that references this issue
on Jul 29, 2023 - added a commit that references this issue
on Sep 22, 2023 - added a commit that references this issue
on May 16, 2024 - added a commit that references this issue
on May 30, 2024 3 remaining items
- added a commit that references this issue
on Jul 15, 2024 - added a commit that references this issue
on Jan 9, 2025 - added 2 commits that reference this issue
on Jul 10, 2025 - added 9 commits that reference this issue
on May 22, 2026
Feature or enhancement
Previously, we have documented that
utcnowandutcfromtimestampshould not be used, but we didn't go so far as to actually deprecate them, and I wrote a whole article about how you shouldn't use them.The main reason I had for not deprecating them at the time was that
.utcnow()is faster than.now(datetime.UTC), and if you are immediately converting the datetime to a string, likedatetime.utcnow().isoformat(), there's no danger.I have come around to the idea that this type of use case is not important enough to leave the attractive nuisances of
utcnow()andutcfromtimestamp()in place, and we should go ahead and deprecate them.Pitch
We should deprecate them in the documentation and also add
DeprecationWarnings imploring people not to use them. I'm OK with us saying that we will remove them "at some point in the future" and not necessarily putting a deadline on it, considering how much use ofutcnow()is out there.Previous discussion
Linked PRs